asecli 0.6.2__py3-none-any.whl

asecli/core/model.py

@@ -0,0 +1,237 @@
+"""Core ASE graph data model (TASK-0003/TASK-0004)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+from collections import Counter
+
+
+@dataclass
+class NodeLine:
+    """A raw ``Node;`` instruction line from the ASEBEGIN block."""
+
+    type_name: str
+    node_id: str
+    raw_fields: list[str]
+
+    def to_line(self) -> str:
+        return ";".join(self.raw_fields)
+
+
+@dataclass
+class WireLine:
+    """A raw ``WireConnection;`` instruction.
+
+    ASE format: ``WireConnection;<in_node>;<in_port>;<out_node>;<out_port>``
+    (destination first, source second — verified against real files).
+    """
+
+    out_node: str
+    out_port: str
+    in_node: str
+    in_port: str
+
+    def to_line(self) -> str:
+        return f"WireConnection;{self.in_node};{self.in_port};{self.out_node};{self.out_port}"
+
+
+@dataclass
+class AseGraph:
+    """Parsed representation of one ASEBEGIN..ASEEND block.
+
+    Preserves the raw instruction stream so that serialize(parse(x)) == x
+    byte-for-byte, and mutations produce minimal diffs. Unrecognized lines
+    (canvas params, comments, future ASE additions) are kept verbatim.
+    """
+
+    version: str = ""
+    instructions: list[tuple[str, str]] = field(default_factory=list)  # (kind, raw)
+    eol: str = "\n"
+    version_eol: str = "\n"
+    line_endings: list[str] = field(default_factory=list)
+
+    def node_by_id(self, node_id: str) -> NodeLine | None:
+        for kind, raw in self.instructions:
+            if kind == "node":
+                n = parse_node_line(raw)
+                if n.node_id == node_id:
+                    return n
+        return None
+
+    @property
+    def nodes(self) -> list[NodeLine]:
+        return [parse_node_line(raw) for kind, raw in self.instructions if kind == "node"]
+
+    @property
+    def wires(self) -> list[WireLine]:
+        return [_parse_wire_line(raw) for kind, raw in self.instructions if kind == "wire"]
+
+    def replace_node(self, node: NodeLine) -> None:
+        for i, (kind, raw) in enumerate(self.instructions):
+            if kind == "node" and parse_node_line(raw).node_id == node.node_id:
+                self.instructions[i] = ("node", node.to_line())
+                return
+        raise KeyError(f"node id {node.node_id} not found")
+
+    def add_node(self, node: NodeLine) -> None:
+        if self.node_by_id(node.node_id) is not None:
+            raise ValueError(f"node id {node.node_id} already exists")
+        self._prepare_append()
+        self.instructions.append(("node", node.to_line()))
+        self.line_endings.append(self.eol)
+
+    def add_wire(self, wire: WireLine) -> None:
+        self._prepare_append()
+        self.instructions.append(("wire", wire.to_line()))
+        self.line_endings.append(self.eol)
+
+    def remove_wire(self, out_node: str, out_port: str, in_node: str, in_port: str) -> bool:
+        target = (out_node, out_port, in_node, in_port)
+        for i, (kind, raw) in enumerate(self.instructions):
+            if kind == "wire":
+                w = _parse_wire_line(raw)
+                if (w.out_node, w.out_port, w.in_node, w.in_port) == target:
+                    self.delete_instruction(i)
+                    return True
+        return False
+
+    def serialize(self) -> str:
+        version = f"Version={self.version}" if not self.version.startswith("Version=") else self.version
+        parts = [version + self.version_eol]
+        for index, (_, raw) in enumerate(self.instructions):
+            ending = self.line_endings[index] if index < len(self.line_endings) else self.eol
+            parts.append(raw + ending)
+        return "".join(parts)
+
+    def delete_instruction(self, index: int) -> None:
+        del self.instructions[index]
+        if index < len(self.line_endings):
+            del self.line_endings[index]
+
+    def _prepare_append(self) -> None:
+        while len(self.line_endings) < len(self.instructions):
+            self.line_endings.append(self.eol)
+        if self.instructions:
+            if self.line_endings[len(self.instructions) - 1] == "":
+                self.line_endings[len(self.instructions) - 1] = self.eol
+        elif not self.instructions and self.version_eol == "":
+            self.version_eol = self.eol
+
+
+def parse_graph_text(body: str) -> AseGraph:
+    """Parse the text between ``/*ASEBEGIN`` and ``ASEEND*/``.
+
+    The body excludes the markers themselves; first line is ``Version=..``.
+    Raises ``ValueError`` on structural violations.
+    """
+    graph = AseGraph()
+    encoded_lines = body.splitlines(keepends=True)
+    if not encoded_lines:
+        raise ValueError("empty ASE graph body")
+    first, graph.version_eol = _split_line_ending(encoded_lines[0])
+    if not first.startswith("Version="):
+        raise ValueError(f"first graph line must be Version=..., got: {first!r}")
+    graph.version = first.removeprefix("Version=")
+    observed_endings = [graph.version_eol] if graph.version_eol else []
+    for encoded in encoded_lines[1:]:
+        line, ending = _split_line_ending(encoded)
+        if not line:
+            graph.instructions.append(("other", ""))
+        elif line.startswith("Node;"):
+            parse_node_line(line)
+            graph.instructions.append(("node", line))
+        elif line.startswith("WireConnection;"):
+            _parse_wire_line(line)
+            graph.instructions.append(("wire", line))
+        else:
+            graph.instructions.append(("other", line))
+        graph.line_endings.append(ending)
+        if ending:
+            observed_endings.append(ending)
+    if observed_endings:
+        counts = Counter(observed_endings)
+        graph.eol = max(counts, key=lambda item: (counts[item], item == graph.version_eol))
+    return graph
+
+
+def _split_line_ending(line: str) -> tuple[str, str]:
+    if line.endswith("\r\n"):
+        return line[:-2], "\r\n"
+    if line.endswith("\n") or line.endswith("\r"):
+        return line[:-1], line[-1]
+    return line, ""
+
+
+def parse_node_line(line: str) -> NodeLine:
+    """Parse one serialized ``Node;...`` instruction."""
+    fields = line.split(";")
+    if len(fields) < 4:
+        raise ValueError(f"malformed Node line: {line!r}")
+    return NodeLine(type_name=fields[1], node_id=fields[2], raw_fields=fields)
+
+
+# Compatibility alias for callers from the pre-0.2 private API period.
+_parse_node_line = parse_node_line
+
+
+def _parse_wire_line(line: str) -> WireLine:
+    fields = line.split(";")
+    if len(fields) != 5:
+        raise ValueError(f"malformed WireConnection line: {line!r}")
+    return WireLine(in_node=fields[1], in_port=fields[2], out_node=fields[3], out_port=fields[4])
+
+
+BEGIN = "/*ASEBEGIN"
+END = "ASEEND*/"
+CHECKSUM_PREFIX = "//CHKSM="
+
+
+@dataclass
+class AseFile:
+    """A shader/function file containing exactly one ASE graph block."""
+
+    prefix: str
+    body: str  # between BEGIN (exclusive) and END (exclusive)
+    suffix: str  # from END marker through checksum line(s)
+    graph: AseGraph = field(default_factory=AseGraph)
+    source_digest: str | None = None
+
+    @classmethod
+    def from_text(cls, text: str) -> "AseFile":
+        begin = text.find(BEGIN)
+        if begin < 0:
+            raise ValueError("no /*ASEBEGIN marker found")
+        end = text.find(END, begin)
+        if end < 0:
+            raise ValueError("no ASEEND*/ marker found")
+        prefix = text[: begin + len(BEGIN)]
+        # body starts after the newline following BEGIN, ends before END marker
+        body_start = begin + len(BEGIN)
+        if text[body_start : body_start + 2] == "\r\n":
+            body_start += 2
+            prefix += "\r\n"
+        elif text[body_start] == "\n":
+            body_start += 1
+            prefix += "\n"
+        body = text[body_start:end]
+        suffix = text[end:]
+        graph = parse_graph_text(body)
+        return cls(prefix=prefix, body=body, suffix=suffix, graph=graph)
+
+    @classmethod
+    def from_path(cls, path: str | __import__("pathlib").Path) -> "AseFile":
+        from pathlib import Path as _P
+
+        data = _P(path).read_bytes()
+        result = cls.from_text(data.decode("utf-8"))
+        result.source_digest = hashlib.sha256(data).hexdigest()
+        return result
+
+    def serialize(self) -> str:
+        """Rebuild full text; without mutations this is byte-identical to source."""
+        return self.prefix + self.graph.serialize() + self.suffix
+
+    def replace_graph(self, graph: AseGraph) -> None:
+        """Replace only the ASE graph while preserving this file's outer shell."""
+        self.graph = graph

asecli/core/property_presentation.py

@@ -0,0 +1,233 @@
+"""Machine-checkable presentation contract for ASECLI-managed properties."""
+
+from __future__ import annotations
+
+import re
+
+from .compiled_properties import inspect_compiled_properties
+from .custom_gui_versions import require_property_metadata_tail_version
+from .model import AseFile
+
+
+PROPERTY_PRESENTATION_CONTRACT = {
+    "contract": "asecli.property-presentation.v2",
+    "scope": "exported_properties",
+    "display_name": {"language": "zh-Hans", "requires_han": True},
+    "tooltip": {
+        "attribute": "TooltipMzgui",
+        "language": "zh-Hans",
+        "requires_han": True,
+        "providers": ["MZGUI.MZGUI", "ASECLI.MaterialGUI.ASECLIMaterialGUI"],
+        "automatic_fields": ["property_name", "shader_default_value"],
+        "property_name_format": "english_identifier",
+    },
+    "help_box": {
+        "required": False,
+        "user_authored": True,
+        "attributes": ["HelpBoxMzgui", "ASECLIHelpBox"],
+    },
+}
+
+_HAN = re.compile(r"[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
+_ENGLISH_PROPERTY_NAME = re.compile(r"^_[A-Za-z][A-Za-z0-9_]*$")
+
+
+def contains_han(text: object) -> bool:
+    return isinstance(text, str) and bool(_HAN.search(text))
+
+
+def set_property_display_name(ase_file: AseFile, node_id: str, display_name: str) -> dict:
+    """Set the graph and compiled ShaderLab display name as one semantic change."""
+    if not isinstance(display_name, str) or not display_name.strip() or len(display_name) > 128:
+        raise ValueError("property display_name must be a non-empty string of at most 128 characters")
+    if any(char in display_name for char in ('"', "'", ";", "\\", "\r", "\n")):
+        raise ValueError("property display_name contains a forbidden quote, separator, escape, or newline")
+    if not contains_han(display_name):
+        raise ValueError("property display_name must contain Chinese characters")
+    require_property_metadata_tail_version(ase_file.graph)
+    node = ase_file.graph.node_by_id(node_id)
+    if node is None:
+        raise KeyError(f"node {node_id} not found")
+    if len(node.raw_fields) <= 8 or node.raw_fields[6] != "Property":
+        raise ValueError(f"node {node_id} is not an exported PropertyNode with a display name")
+
+    property_name = node.raw_fields[7]
+    pattern = re.compile(
+        rf'(?m)^(?P<head>[ \t]*(?:\[[^\]\r\n]*\][ \t]*)*{re.escape(property_name)}[ \t]*\([ \t]*")'
+        r'(?P<label>[^"\r\n]*)(?P<tail>"[ \t]*,)'
+    )
+    matches = list(pattern.finditer(ase_file.prefix))
+    if len(matches) != 1:
+        raise ValueError(
+            f"expected one compiled ShaderLab declaration for {property_name!r}, found {len(matches)}"
+        )
+    match = matches[0]
+    before_graph = node.raw_fields[8]
+    before_compiled = match.group("label")
+    node.raw_fields[8] = display_name
+    ase_file.graph.replace_node(node)
+    ase_file.prefix = (
+        ase_file.prefix[: match.start("label")]
+        + display_name
+        + ase_file.prefix[match.end("label") :]
+    )
+    return {
+        "kind": "property_display_name",
+        "node_id": node_id,
+        "property_name": property_name,
+        "before": {"graph": before_graph, "compiled": before_compiled},
+        "after": display_name,
+    }
+
+
+def inspect_property_presentation(
+    editor: dict,
+    properties: list[dict],
+    compiled_source: str,
+    *,
+    supported_editors: frozenset[str],
+) -> dict:
+    """Inspect already-parsed Custom GUI state without importing graph modules."""
+    claimed = (
+        editor.get("graph") in supported_editors
+        or editor.get("compiled") in supported_editors
+    )
+    managed = (
+        editor.get("graph") in supported_editors
+        and editor.get("compiled") == editor.get("graph")
+        and editor.get("consistent") is True
+    )
+    violations: list[str] = []
+    if not managed:
+        violations.append("editor:mzgui_compatible_material_gui_required")
+
+    compiled_properties, compiled_properties_error = inspect_compiled_properties(compiled_source)
+    if compiled_properties_error is not None:
+        violations.append("inspection:compiled_properties_unavailable")
+
+    graph_by_name = _unique_properties(properties, "graph", violations)
+    compiled_by_name = _unique_properties(compiled_properties, "compiled", violations)
+    graph_names = set(graph_by_name)
+    compiled_names = set(compiled_by_name)
+    visible_compiled_names = {
+        name for name, prop in compiled_by_name.items() if not prop.get("hidden", False)
+    }
+    graph_only = sorted(graph_names - compiled_names) if compiled_properties_error is None else []
+    compiled_only = sorted(visible_compiled_names - graph_names) if compiled_properties_error is None else []
+    violations.extend(f"property:{name}:compiled_property_required" for name in graph_only)
+    violations.extend(f"compiled_property:{name}:graph_property_required" for name in compiled_only)
+
+    property_results = []
+    for prop in properties:
+        property_name = prop.get("property_name")
+        property_violations = []
+        if not isinstance(property_name, str) or not _ENGLISH_PROPERTY_NAME.fullmatch(property_name):
+            property_violations.append("property_name:english_identifier_required")
+        if not contains_han(prop.get("display_name")):
+            property_violations.append("display_name:chinese_required")
+        tooltip_values = [
+            item.get("text")
+            for item in prop.get("attributes", [])
+            if item.get("type") in {"TooltipMzgui", "ASECLITooltip"}
+        ]
+        if len(tooltip_values) != 1 or not contains_han(tooltip_values[0]):
+            property_violations.append("tooltip:chinese_required")
+        compiled = compiled_by_name.get(property_name)
+        if compiled is not None:
+            compiled_display_name = compiled.get("display_name")
+            if not contains_han(compiled_display_name):
+                property_violations.append("compiled_display_name:chinese_required")
+            if compiled_display_name != prop.get("display_name"):
+                property_violations.append("display_name:graph_compiled_mismatch")
+            compiled_tooltip_values = [
+                item.get("text")
+                for item in compiled.get("attributes", [])
+                if item.get("type") in {"TooltipMzgui", "ASECLITooltip"}
+            ]
+            if len(compiled_tooltip_values) != 1 or not contains_han(compiled_tooltip_values[0]):
+                property_violations.append("compiled_tooltip:chinese_required")
+            if tooltip_values != compiled_tooltip_values:
+                property_violations.append("tooltip:graph_compiled_mismatch")
+        label = property_name if isinstance(property_name, str) else str(prop.get("node_id"))
+        violations.extend(f"property:{label}:{item}" for item in property_violations)
+        property_results.append(
+            {
+                "node_id": prop.get("node_id"),
+                "property_name": property_name,
+                "display_name": prop.get("display_name"),
+                "compiled_display_name": compiled.get("display_name") if compiled else None,
+                "valid": not property_violations,
+                "violations": property_violations,
+            }
+        )
+
+    return {
+        **PROPERTY_PRESENTATION_CONTRACT,
+        "claimed": claimed,
+        "managed": managed,
+        "inspection": "error" if compiled_properties_error is not None else "complete",
+        "inspection_error": compiled_properties_error,
+        "valid": managed and not violations,
+        "violations": violations,
+        "properties": property_results,
+        "graph_properties": sorted(graph_names),
+        "compiled_properties": sorted(compiled_names),
+        "reconciliation": {
+            "matched": sorted(graph_names & compiled_names),
+            "graph_only": graph_only,
+            "compiled_only": compiled_only,
+        },
+    }
+
+
+def require_managed_property_presentation(ase_file: AseFile) -> dict | None:
+    """Fail closed only after a file claims an MZGUI-compatible material GUI."""
+    from .custom_gui import inspect_custom_gui
+
+    try:
+        result = inspect_custom_gui(ase_file)["property_presentation"]
+    except ValueError as exc:
+        if not _has_asecli_presentation_marker(ase_file):
+            return None
+        raise ValueError(
+            f"MZGUI-compatible property presentation inspection failed: {exc}"
+        ) from exc
+    if result["valid"]:
+        return result
+    if not result["claimed"] and not _has_asecli_presentation_marker(ase_file):
+        return result
+    raise ValueError(
+        "MZGUI-compatible property presentation contract failed: "
+        + ", ".join(result["violations"])
+    )
+
+
+def require_property_presentation(ase_file: AseFile) -> dict:
+    """Require the complete contract for a newly constructed ASE shader."""
+    from .custom_gui import inspect_custom_gui
+
+    result = inspect_custom_gui(ase_file)["property_presentation"]
+    if result["valid"]:
+        return result
+    raise ValueError(
+        "ASE property presentation contract failed: " + ", ".join(result["violations"])
+    )
+
+
+def _unique_properties(properties: list[dict], source: str, violations: list[str]) -> dict[str, dict]:
+    result: dict[str, dict] = {}
+    for prop in properties:
+        name = prop.get("property_name")
+        if not isinstance(name, str):
+            violations.append(f"{source}_property:unknown:property_name_required")
+            continue
+        if name in result:
+            violations.append(f"{source}_property:{name}:duplicate")
+            continue
+        result[name] = prop
+    return result
+
+
+def _has_asecli_presentation_marker(ase_file: AseFile) -> bool:
+    text = ase_file.serialize()
+    return any(editor in text for editor in PROPERTY_PRESENTATION_CONTRACT["tooltip"]["providers"]) or "Mzgui" in text or "[ASECLI" in text

asecli/core/wire_geometry.py

@@ -0,0 +1,83 @@
+"""Approximate ASE Bezier paths for deterministic layout diagnostics."""
+
+from __future__ import annotations
+
+from typing import Mapping, Protocol
+
+from .model import AseGraph, WireLine
+
+
+class Geometry(Protocol):
+    width: float
+    height: float
+    input_ports: dict[str, tuple[float, float]]
+    output_ports: dict[str, tuple[float, float]]
+
+
+def wire_paths(
+    graph: AseGraph,
+    geometry: Mapping[str, Geometry],
+    positions: Mapping[str, tuple[float, float]],
+    *,
+    samples: int = 24,
+) -> list[tuple[WireLine, list[tuple[float, float]]]]:
+    result = []
+    for wire in graph.wires:
+        if wire.out_node not in positions or wire.in_node not in positions:
+            continue
+        source = _anchor(wire.out_node, wire.out_port, True, geometry, positions)
+        target = _anchor(wire.in_node, wire.in_port, False, geometry, positions)
+        span = max(48.0, abs(target[0] - source[0]) * 0.5)
+        control_a = (source[0] + span, source[1])
+        control_b = (target[0] - span, target[1])
+        path = [_bezier(source, control_a, control_b, target, step / samples) for step in range(samples + 1)]
+        result.append((wire, path))
+    return result
+
+
+def path_hits_rect(path: list[tuple[float, float]], rect: tuple[float, float, float, float]) -> bool:
+    return any(segment_hits_rect(left, right, rect) for left, right in zip(path, path[1:]))
+
+
+def segment_hits_rect(a, b, rect) -> bool:
+    left, top, right, bottom = rect
+    if left <= a[0] <= right and top <= a[1] <= bottom:
+        return True
+    if left <= b[0] <= right and top <= b[1] <= bottom:
+        return True
+    corners = [(left, top), (right, top), (right, bottom), (left, bottom)]
+    return any(_segments_cross(a, b, corners[index], corners[(index + 1) % 4]) for index in range(4))
+
+
+def paths_cross(left: list[tuple[float, float]], right: list[tuple[float, float]]) -> bool:
+    for a, b in zip(left, left[1:]):
+        for c, d in zip(right, right[1:]):
+            if _segments_cross(a, b, c, d):
+                return True
+    return False
+
+
+def _anchor(node_id, port_id, output, geometry, positions) -> tuple[float, float]:
+    offsets = geometry[node_id].output_ports if output else geometry[node_id].input_ports
+    dx, dy = offsets[port_id]
+    x, y = positions[node_id]
+    return x + dx, y + dy
+
+
+def _bezier(p0, p1, p2, p3, t: float) -> tuple[float, float]:
+    one = 1.0 - t
+    return (
+        one ** 3 * p0[0] + 3 * one * one * t * p1[0] + 3 * one * t * t * p2[0] + t ** 3 * p3[0],
+        one ** 3 * p0[1] + 3 * one * one * t * p1[1] + 3 * one * t * t * p2[1] + t ** 3 * p3[1],
+    )
+
+
+def _segments_cross(a, b, c, d) -> bool:
+    def orient(p, q, r):
+        return (q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0])
+    ab_c, ab_d = orient(a, b, c), orient(a, b, d)
+    cd_a, cd_b = orient(c, d, a), orient(c, d, b)
+    epsilon = 1e-6
+    return ((ab_c > epsilon and ab_d < -epsilon) or (ab_c < -epsilon and ab_d > epsilon)) and (
+        (cd_a > epsilon and cd_b < -epsilon) or (cd_a < -epsilon and cd_b > epsilon)
+    )