asecli 0.6.2__py3-none-any.whl

asecli/core/local_vars.py

@@ -0,0 +1,54 @@
+"""ASE Register/Get Local Var semantic references."""
+
+from __future__ import annotations
+
+from .model import AseGraph, NodeLine
+
+
+REGISTER_LOCAL_VAR_TYPE = "AmplifyShaderEditor.RegisterLocalVarNode"
+GET_LOCAL_VAR_TYPE = "AmplifyShaderEditor.GetLocalVarNode"
+
+
+def parse_register_local_var(node: NodeLine) -> dict:
+    if node.type_name != REGISTER_LOCAL_VAR_TYPE:
+        raise ValueError(f"node {node.node_id} is not a RegisterLocalVarNode")
+    if len(node.raw_fields) < 16:
+        raise ValueError(f"RegisterLocalVarNode {node.node_id} has too few serialized fields")
+    return {
+        "node_id": node.node_id,
+        "name": node.raw_fields[6],
+        "data_type": node.raw_fields[15],
+    }
+
+
+def parse_get_local_var(node: NodeLine) -> dict:
+    if node.type_name != GET_LOCAL_VAR_TYPE:
+        raise ValueError(f"node {node.node_id} is not a GetLocalVarNode")
+    if len(node.raw_fields) < 15:
+        raise ValueError(f"GetLocalVarNode {node.node_id} has too few serialized fields")
+    return {
+        "node_id": node.node_id,
+        "register_id": node.raw_fields[6],
+        "name": node.raw_fields[7],
+        "data_type": node.raw_fields[14],
+    }
+
+
+def local_var_edges(graph: AseGraph) -> list[tuple[str, str]]:
+    """Return valid semantic data-flow edges as ``Register -> Get``."""
+    registers = {
+        node.node_id
+        for node in graph.nodes
+        if node.type_name == REGISTER_LOCAL_VAR_TYPE
+    }
+    edges = []
+    for node in graph.nodes:
+        if node.type_name != GET_LOCAL_VAR_TYPE:
+            continue
+        try:
+            item = parse_get_local_var(node)
+        except ValueError:
+            continue
+        if item["register_id"] in registers:
+            edges.append((item["register_id"], node.node_id))
+    return edges

asecli/core/material_gui_condition.py

@@ -0,0 +1,68 @@
+"""Portable conditional-enable metadata for MZGUI-compatible inspectors."""
+
+from __future__ import annotations
+
+import math
+import re
+
+
+ENABLE_IF_ATTRIBUTE = "EnableIfMzgui"
+ENABLE_IF_OPERATORS = (
+    "Less",
+    "LessEqual",
+    "Equal",
+    "NotEqual",
+    "GreaterEqual",
+    "Greater",
+)
+_PROPERTY_NAME = re.compile(r"^_[A-Za-z][A-Za-z0-9_]{0,127}$")
+
+
+def enable_if_attribute(property_name: str, operator: str, value: int | float) -> str:
+    """Encode one conditional-enable rule as a ShaderLab property attribute."""
+    condition = validate_enable_if(
+        {"property": property_name, "operator": operator, "value": value}
+    )
+    number = format(condition["value"], ".9g")
+    return (
+        f'[{ENABLE_IF_ATTRIBUTE}({condition["property"]},'
+        f'{condition["operator"]},{number})]'
+    )
+
+
+def parse_enable_if_arguments(arguments: str) -> dict:
+    """Decode the comma-separated payload stored by EnableIfMzgui."""
+    parts = [part.strip() for part in arguments.split(",")]
+    if len(parts) != 3:
+        raise ValueError("EnableIfMzgui requires property, operator, and numeric value")
+    try:
+        value = float(parts[2])
+    except ValueError as exc:
+        raise ValueError("EnableIfMzgui value must be a finite number") from exc
+    return validate_enable_if(
+        {"property": parts[0], "operator": parts[1], "value": value}
+    )
+
+
+def validate_enable_if(value: object) -> dict:
+    """Validate a JSON-compatible conditional-enable object."""
+    if not isinstance(value, dict):
+        raise ValueError("enabled_if must be an object")
+    unknown = set(value) - {"property", "operator", "value"}
+    if unknown:
+        raise ValueError(f"enabled_if has unknown keys: {sorted(unknown)}")
+    property_name = value.get("property")
+    if not isinstance(property_name, str) or not _PROPERTY_NAME.fullmatch(property_name):
+        raise ValueError("enabled_if.property must be an underscored Shader property name")
+    operator = value.get("operator", "Equal")
+    if operator not in ENABLE_IF_OPERATORS:
+        raise ValueError(
+            "enabled_if.operator must be one of " + ", ".join(ENABLE_IF_OPERATORS)
+        )
+    number = value.get("value")
+    if isinstance(number, bool) or not isinstance(number, (int, float)):
+        raise ValueError("enabled_if.value must be a finite number")
+    number = float(number)
+    if not math.isfinite(number):
+        raise ValueError("enabled_if.value must be a finite number")
+    return {"property": property_name, "operator": operator, "value": number}

asecli/core/material_gui_protocol.py

@@ -0,0 +1,35 @@
+"""Shared MZGUI metadata protocol and legacy migration aliases."""
+
+PROPERTY_METADATA_ATTRIBUTE_TYPES = (
+    "FoldoutMzgui",
+    "TooltipMzgui",
+    "HelpBoxMzgui",
+    "EnableIfMzgui",
+)
+LEGACY_PROPERTY_METADATA_ATTRIBUTE_TYPES = (
+    "ASECLIFoldout",
+    "ASECLITooltip",
+    "ASECLIHelpBox",
+    "ASECLIEnableIf",
+)
+_LEGACY_BY_CANONICAL = dict(
+    zip(PROPERTY_METADATA_ATTRIBUTE_TYPES, LEGACY_PROPERTY_METADATA_ATTRIBUTE_TYPES)
+)
+_CANONICAL_BY_ATTRIBUTE = {
+    **{name: name for name in PROPERTY_METADATA_ATTRIBUTE_TYPES},
+    **{legacy: canonical for canonical, legacy in _LEGACY_BY_CANONICAL.items()},
+}
+MANAGED_PROPERTY_METADATA_ATTRIBUTE_TYPES = frozenset(_CANONICAL_BY_ATTRIBUTE)
+
+
+def canonical_property_metadata_type(type_name: str) -> str | None:
+    """Return the public MZGUI type for a public or historical ASECLI type."""
+    return _CANONICAL_BY_ATTRIBUTE.get(type_name)
+
+
+def equivalent_property_metadata_types(type_name: str) -> frozenset[str]:
+    """Return the MZGUI type and its one legacy ASECLI alias."""
+    canonical = canonical_property_metadata_type(type_name)
+    if canonical is None:
+        return frozenset()
+    return frozenset((canonical, _LEGACY_BY_CANONICAL[canonical]))

asecli/core/material_gui_spec.py

@@ -0,0 +1,191 @@
+"""Declarative, atomic material-property ordering and ASECLI metadata specs."""
+
+from __future__ import annotations
+
+from .custom_gui import (
+    SUPPORTED_GUI_EDITORS,
+    graph_custom_editor,
+    is_material_property_node,
+    remove_property_metadata_attribute,
+    semantic_attribute,
+    set_custom_editor,
+    set_property_metadata_attribute,
+)
+from .custom_gui_versions import require_property_metadata_tail_version
+from .material_gui_condition import enable_if_attribute, validate_enable_if
+from .model import AseFile, AseGraph, NodeLine
+from .property_presentation import set_property_display_name
+
+
+_TOP_KEYS = {"editor", "reorder", "properties"}
+_PROPERTY_KEYS = {
+    "name", "node", "display_name", "group", "help", "tooltip", "enabled_if"
+}
+_SEMANTIC_TYPES = {
+    "group": "FoldoutMzgui",
+    "help": "HelpBoxMzgui",
+    "tooltip": "TooltipMzgui",
+}
+
+
+def material_property_nodes(graph: AseGraph) -> list[NodeLine]:
+    return [node for node in graph.nodes if is_material_property_node(node)]
+
+
+def resolve_property_node(
+    graph: AseGraph,
+    *,
+    node_id: str | None = None,
+    property_name: str | None = None,
+) -> NodeLine:
+    """Resolve an exported property by node id or exact ShaderLab property name."""
+    if (node_id is None) == (property_name is None):
+        raise ValueError("provide exactly one of node id or property name")
+    if node_id is not None:
+        node = graph.node_by_id(node_id)
+        if node is None:
+            raise KeyError(f"node {node_id} not found")
+        if not is_material_property_node(node):
+            raise ValueError(f"node {node_id} is not an exported PropertyNode")
+        return node
+    matches = [node for node in material_property_nodes(graph) if node.raw_fields[7] == property_name]
+    if len(matches) != 1:
+        raise ValueError(f"expected one exported property named {property_name!r}, found {len(matches)}")
+    return matches[0]
+
+
+def apply_material_gui_spec(ase_file: AseFile, spec: dict) -> list[dict]:
+    """Apply a declarative property order/group/tooltip/optional-help spec in memory."""
+    if not isinstance(spec, dict):
+        raise ValueError("material GUI spec root must be a JSON object")
+    unknown = set(spec) - _TOP_KEYS
+    if unknown:
+        raise ValueError(f"unknown material GUI spec keys: {sorted(unknown)}")
+    entries = spec.get("properties", [])
+    if not isinstance(entries, list):
+        raise ValueError("material GUI spec 'properties' must be an array")
+    reorder = spec.get("reorder", False)
+    if not isinstance(reorder, bool):
+        raise ValueError("material GUI spec 'reorder' must be boolean")
+
+    changes: list[dict] = []
+    editor = spec.get("editor")
+    if editor is not None:
+        if not isinstance(editor, str):
+            raise ValueError("material GUI spec 'editor' must be a class-name string")
+        changes.append(set_custom_editor(ase_file, editor))
+
+    resolved: list[tuple[NodeLine, dict]] = []
+    seen: set[str] = set()
+    has_additions = False
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise ValueError(f"properties[{index}] must be an object")
+        unknown = set(entry) - _PROPERTY_KEYS
+        if unknown:
+            raise ValueError(f"properties[{index}] has unknown keys: {sorted(unknown)}")
+        has_name = "name" in entry
+        has_node = "node" in entry
+        if has_name == has_node:
+            raise ValueError(f"properties[{index}] must provide exactly one of 'name' or 'node'")
+        if has_name and not isinstance(entry["name"], str):
+            raise ValueError(f"properties[{index}] field 'name' must be a string")
+        if has_node and not isinstance(entry["node"], (str, int)):
+            raise ValueError(f"properties[{index}] field 'node' must be a string or integer")
+        node = resolve_property_node(
+            ase_file.graph,
+            node_id=str(entry["node"]) if has_node else None,
+            property_name=entry.get("name"),
+        )
+        if node.node_id in seen:
+            raise ValueError(f"property node {node.node_id} appears more than once in spec")
+        seen.add(node.node_id)
+        resolved.append((node, entry))
+        has_additions |= any(entry.get(key) is not None for key in _SEMANTIC_TYPES if key in entry)
+        has_additions |= entry.get("enabled_if") is not None
+
+    active_editor = graph_custom_editor(ase_file.graph)
+    if has_additions and active_editor not in SUPPORTED_GUI_EDITORS:
+        supported = ", ".join(sorted(SUPPORTED_GUI_EDITORS))
+        raise ValueError(f"MZGUI-compatible property metadata requires a selected material GUI: {supported}")
+    if reorder and not resolved:
+        raise ValueError("reorder=true requires at least one property entry")
+    if reorder:
+        require_property_metadata_tail_version(ase_file.graph)
+        changes.extend(_reorder_properties(ase_file.graph, [node for node, _ in resolved]))
+
+    for node, entry in resolved:
+        if "display_name" in entry:
+            display_name = entry["display_name"]
+            if not isinstance(display_name, str):
+                raise ValueError(
+                    f"property {node.raw_fields[7]} field 'display_name' must be a string"
+                )
+            changes.append(set_property_display_name(ase_file, node.node_id, display_name))
+        for key, type_name in _SEMANTIC_TYPES.items():
+            if key not in entry:
+                continue
+            value = entry[key]
+            if value is None:
+                changes.append(remove_property_metadata_attribute(ase_file.graph, node.node_id, type_name))
+            elif isinstance(value, str):
+                changes.append(
+                    set_property_metadata_attribute(ase_file.graph, node.node_id, semantic_attribute(type_name, value))
+                )
+            else:
+                raise ValueError(f"property {node.raw_fields[7]} field {key!r} must be string or null")
+        if "enabled_if" in entry:
+            condition = entry["enabled_if"]
+            if condition is None:
+                changes.append(
+                    remove_property_metadata_attribute(
+                        ase_file.graph, node.node_id, "EnableIfMzgui"
+                    )
+                )
+            else:
+                validated = validate_enable_if(condition)
+                changes.append(
+                    set_property_metadata_attribute(
+                        ase_file.graph,
+                        node.node_id,
+                        enable_if_attribute(
+                            validated["property"],
+                            validated["operator"],
+                            validated["value"],
+                        ),
+                    )
+                )
+    return changes
+
+
+def _reorder_properties(graph: AseGraph, requested: list[NodeLine]) -> list[dict]:
+    all_nodes = material_property_nodes(graph)
+    requested_ids = {node.node_id for node in requested}
+    instruction_order = {node.node_id: index for index, node in enumerate(all_nodes)}
+
+    def current_order(node: NodeLine) -> tuple[int, int]:
+        try:
+            value = int(node.raw_fields[9])
+        except (IndexError, ValueError):
+            value = 2**31 - 1
+        return value, instruction_order[node.node_id]
+
+    remaining = sorted((node for node in all_nodes if node.node_id not in requested_ids), key=current_order)
+    changes = []
+    for order, node in enumerate([*requested, *remaining]):
+        before = node.raw_fields[9]
+        after = str(order)
+        if before == after:
+            continue
+        node.raw_fields[9] = after
+        graph.replace_node(node)
+        changes.append(
+            {
+                "kind": "property_order",
+                "node_id": node.node_id,
+                "property_name": node.raw_fields[7],
+                "before": before,
+                "after": after,
+            }
+        )
+    return changes

asecli/core/meticulous_layout.py

@@ -0,0 +1,114 @@
+"""Public recursive fishbone layout plan and application API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Protocol
+
+from .commentary import inspect_comment_groups
+from .fishbone_placement import place_fishbone
+from .fishbone_topology import build_fishbone_topology
+from .layout import apply_positions
+from .layout_graph import id_key, node_rect
+from .model import AseGraph
+from .wire_router import WIRE_NODE_TYPE, plan_wire_routes
+
+
+class Geometry(Protocol):
+    width: float
+    height: float
+    title_height: float
+    input_ports: dict[str, tuple[float, float]]
+    output_ports: dict[str, tuple[float, float]]
+
+
+@dataclass(frozen=True)
+class MeticulousLayoutPlan:
+    positions: dict[str, tuple[float, float]]
+    primary_parent: dict[str, str]
+    children: dict[str, tuple[str, ...]]
+    ordered_children: dict[str, tuple[str, ...]]
+    spine_child: dict[str, str]
+    roots: tuple[str, ...]
+    depths: dict[str, int]
+    stage_output_x: dict[str, float]
+    subtree_bounds: dict[str, tuple[float, float, float, float]]
+    horizontal_edges: tuple[tuple[str, str, str, str], ...]
+    secondary_edges: tuple[tuple[str, str, str, str], ...]
+    comment_snapshot: tuple[tuple[str, tuple[str, ...], str], ...]
+    wire_route_changes: tuple[dict, ...] = ()
+
+
+def meticulous_layout_positions(
+    graph: AseGraph,
+    geometry: Mapping[str, Geometry],
+    *,
+    route_wires: bool = False,
+) -> MeticulousLayoutPlan:
+    topology = build_fishbone_topology(graph, geometry)
+    positions, roots, stage_output_x = place_fishbone(graph, geometry, topology)
+    subtree_bounds = {}
+    for node_id in sorted(topology.ids, key=id_key):
+        members = _descendants(node_id, topology.children)
+        rects = [
+            node_rect(member, positions, geometry)
+            for member in members if member in positions and member in geometry
+        ]
+        subtree_bounds[node_id] = _union_bounds(rects)
+    horizontal_edges = tuple(sorted(
+        (
+            child, topology.primary_wire[(child, parent)].out_port,
+            parent, topology.primary_wire[(child, parent)].in_port,
+        )
+        for parent, child in topology.spine_child.items()
+        if topology.group_of.get(parent) == topology.group_of.get(child)
+    ))
+    primary_keys = set(topology.primary_parent.items())
+    secondary = tuple(sorted(
+        (wire.out_node, wire.out_port, wire.in_node, wire.in_port)
+        for wire in topology.collapsed_wires
+        if wire.out_node in topology.ids and wire.in_node in topology.ids
+        and (wire.out_node, wire.in_node) not in primary_keys
+    ))
+    comments = tuple(sorted(
+        (group["node_id"], tuple(group["members"]), group["color"])
+        for group in inspect_comment_groups(graph)
+    ))
+    route_changes = plan_wire_routes(graph, geometry, positions) if route_wires else ()
+    return MeticulousLayoutPlan(
+        positions=positions,
+        primary_parent=topology.primary_parent,
+        children=topology.children,
+        ordered_children=topology.children,
+        spine_child=topology.spine_child,
+        roots=tuple(roots),
+        depths=topology.depths,
+        stage_output_x=stage_output_x,
+        subtree_bounds=subtree_bounds,
+        horizontal_edges=horizontal_edges,
+        secondary_edges=secondary,
+        comment_snapshot=comments,
+        wire_route_changes=route_changes,
+    )
+
+
+def apply_meticulous_layout(graph: AseGraph, plan: MeticulousLayoutPlan) -> int:
+    return apply_positions(graph, plan.positions)
+
+
+def _union_bounds(rects):
+    values = list(rects)
+    return (
+        min(rect[0] for rect in values), min(rect[1] for rect in values),
+        max(rect[2] for rect in values), max(rect[3] for rect in values),
+    )
+
+
+def _descendants(node_id: str, children: Mapping[str, tuple[str, ...]]) -> set[str]:
+    result, stack = {node_id}, list(children.get(node_id, ()))
+    while stack:
+        child = stack.pop()
+        if child not in result:
+            result.add(child)
+            stack.extend(children.get(child, ()))
+    return result