asecli 0.6.2__py3-none-any.whl

asecli/core/comment_metrics.py

@@ -0,0 +1,132 @@
+"""Whitespace, outlier, and positioned-bound metrics for ASE Comments."""
+
+from __future__ import annotations
+
+from typing import Mapping, Protocol
+
+from .commentary import inspect_comment_groups
+from .model import AseGraph
+
+SIDE_PADDING = 30.0
+TOP_PADDING = 48.0
+BOTTOM_PADDING = 30.0
+WHITESPACE_TARGET = 0.55
+WHITESPACE_ERROR = 0.65
+HORIZONTAL_FOOTPRINT = 48.0
+VERTICAL_FOOTPRINT = 16.0
+
+
+class Geometry(Protocol):
+    width: float
+    height: float
+
+
+def comment_layout_metrics(
+    graph: AseGraph,
+    geometry: Mapping[str, Geometry],
+    positions: Mapping[str, tuple[float, float]],
+) -> tuple[list[dict], list[dict]]:
+    groups = {group["node_id"]: group for group in inspect_comment_groups(graph)}
+
+    def bounds(member_id: str) -> tuple[float, float, float, float]:
+        if member_id in groups:
+            group = groups[member_id]
+            x, y = group["position"].values()
+            return x, y, x + group["width"], y + group["height"]
+        x, y = positions[member_id]
+        return x, y, x + geometry[member_id].width, y + geometry[member_id].height
+
+    whitespace, outliers = [], []
+    for group_id in sorted(groups, key=_id_key):
+        group = groups[group_id]
+        frame_area = group["width"] * group["height"]
+        member_bounds = [(member_id, bounds(member_id)) for member_id in group["members"]]
+        content_rect = (
+            group["position"]["x"] + SIDE_PADDING,
+            group["position"]["y"] + TOP_PADDING,
+            group["position"]["x"] + group["width"] - SIDE_PADDING,
+            group["position"]["y"] + group["height"] - BOTTOM_PADDING,
+        )
+        footprints = [
+            _clip((
+                rect[0] - HORIZONTAL_FOOTPRINT, rect[1] - VERTICAL_FOOTPRINT,
+                rect[2] + HORIZONTAL_FOOTPRINT, rect[3] + VERTICAL_FOOTPRINT,
+            ), content_rect)
+            for _, rect in member_bounds
+        ]
+        occupied = _rect_union_area([rect for rect in footprints if _area(rect) > 0])
+        ratio = max(0.0, 1.0 - min(1.0, occupied / frame_area))
+        whitespace.append({
+            "comment_id": group_id,
+            "ratio": round(ratio, 4),
+            "status": "error" if ratio > WHITESPACE_ERROR else (
+                "warning" if ratio > WHITESPACE_TARGET else "passed"
+            ),
+        })
+        if len(member_bounds) < 2:
+            continue
+        full = _union(rect for _, rect in member_bounds)
+        full_area = _area(full)
+        for member_id, _ in member_bounds:
+            remaining = [rect for item_id, rect in member_bounds if item_id != member_id]
+            reduction = 0.0 if full_area == 0 else 1.0 - _area(_union(remaining)) / full_area
+            if reduction > 0.35:
+                outliers.append({
+                    "comment_id": group_id, "member_id": member_id,
+                    "area_reduction_if_removed": round(reduction, 4),
+                })
+    return whitespace, outliers
+
+
+def positioned_bounds(geometry, positions):
+    return {
+        node_id: (x, y, geometry[node_id].width, geometry[node_id].height)
+        for node_id, (x, y) in positions.items() if node_id in geometry
+    }
+
+
+def _union(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 _area(rect):
+    return max(0.0, rect[2] - rect[0]) * max(0.0, rect[3] - rect[1])
+
+
+def _clip(rect, bounds):
+    return (
+        max(rect[0], bounds[0]), max(rect[1], bounds[1]),
+        min(rect[2], bounds[2]), min(rect[3], bounds[3]),
+    )
+
+
+def _rect_union_area(rects):
+    if not rects:
+        return 0.0
+    xs = sorted({value for rect in rects for value in (rect[0], rect[2])})
+    area = 0.0
+    for left, right in zip(xs, xs[1:]):
+        spans = sorted(
+            (rect[1], rect[3]) for rect in rects
+            if rect[0] < right and rect[2] > left and rect[3] > rect[1]
+        )
+        if right <= left or not spans:
+            continue
+        start, end = spans[0]
+        covered = 0.0
+        for top, bottom in spans[1:]:
+            if top > end:
+                covered += end - start
+                start, end = top, bottom
+            else:
+                end = max(end, bottom)
+        area += (right - left) * (covered + end - start)
+    return area
+
+
+def _id_key(value: str):
+    return (0, int(value)) if value.lstrip("-").isdigit() else (1, value)

asecli/core/comment_purpose.py

@@ -0,0 +1,140 @@
+"""Conservative purpose-title inference for existing ASE Comment frames."""
+
+from __future__ import annotations
+
+import re
+from typing import Mapping, Protocol
+
+from .commentary import inspect_comment_groups, parse_commentary_node
+from .local_vars import REGISTER_LOCAL_VAR_TYPE, parse_register_local_var
+from .model import AseGraph
+
+_PLACEHOLDER_TITLE = re.compile(
+    r"^(?:comment|group|组|处理\s*\d*|临时(?:组)?\s*\d*)$", re.IGNORECASE,
+)
+
+
+class Geometry(Protocol):
+    node_title: str
+    input_port_labels: dict[str, str] | None
+
+
+def govern_comment_purposes(
+    graph: AseGraph,
+    geometry: Mapping[str, Geometry],
+    *,
+    apply: bool,
+) -> list[dict]:
+    """Preserve meaningful titles and infer only missing algorithm purposes."""
+    groups = {group["node_id"]: group for group in inspect_comment_groups(graph)}
+
+    def leaf_members(group_id: str, visiting: set[str] | None = None) -> set[str]:
+        visiting = set() if visiting is None else visiting
+        if group_id in visiting:
+            raise ValueError(f"comment membership contains a cycle at node {group_id}")
+        visiting.add(group_id)
+        result = set()
+        for member in groups[group_id]["members"]:
+            if member in groups:
+                result.update(leaf_members(member, visiting))
+            else:
+                result.add(member)
+        visiting.remove(group_id)
+        return result
+
+    results = []
+    for group_id in sorted(groups, key=_id_key):
+        group = groups[group_id]
+        title = group["title"].strip()
+        if title and not _PLACEHOLDER_TITLE.fullmatch(title):
+            results.append({"comment_id": group_id, "status": "existing", "title": title})
+            continue
+        suggestion, source = _infer_comment_title(graph, geometry, leaf_members(group_id))
+        if suggestion is None:
+            results.append({
+                "comment_id": group_id,
+                "status": "unresolved",
+                "title": group["title"],
+                "reason": "no_unique_register_consumer_or_algorithm_sink",
+            })
+            continue
+        results.append({
+            "comment_id": group_id,
+            "status": "inferred",
+            "title": group["title"],
+            "suggested_title": suggestion,
+            "source": source,
+        })
+        if apply:
+            node = graph.node_by_id(group_id)
+            if node is None:
+                raise ValueError(f"comment node {group_id} not found")
+            count = int(node.raw_fields[9])
+            node.raw_fields[10 + count] = suggestion
+            graph.replace_node(node)
+            groups[group_id] = parse_commentary_node(node)
+    return results
+
+
+def _infer_comment_title(graph: AseGraph, geometry, members: set[str]):
+    registers = []
+    for member in sorted(members, key=_id_key):
+        node = graph.node_by_id(member)
+        if node is not None and node.type_name == REGISTER_LOCAL_VAR_TYPE:
+            try:
+                name = parse_register_local_var(node)["name"].strip()
+            except ValueError:
+                continue
+            if name:
+                registers.append(name)
+    if len(registers) == 1:
+        return _safe_title(f"生成 {registers[0]}"), "register_local_var"
+
+    outgoing = [
+        wire for wire in graph.wires
+        if wire.out_node in members and wire.in_node not in members
+    ]
+    consumers = {(wire.in_node, wire.in_port) for wire in outgoing}
+    if len(consumers) == 1:
+        consumer_id, in_port = next(iter(consumers))
+        consumer = _node_label(graph, geometry, consumer_id)
+        labels = getattr(geometry.get(consumer_id), "input_port_labels", {}) or {}
+        port_label = str(labels.get(in_port, "")).strip()
+        if _meaningful_label(consumer):
+            if _meaningful_label(port_label):
+                return _safe_title(f"为「{consumer}」计算「{port_label}」"), "external_consumer_port"
+            return _safe_title(f"为「{consumer}」计算输入"), "external_consumer"
+
+    internal_sources = {
+        wire.out_node for wire in graph.wires
+        if wire.out_node in members and wire.in_node in members
+    }
+    sinks = sorted(members - internal_sources, key=_id_key)
+    real_sinks = [item for item in sinks if _meaningful_label(_node_label(graph, geometry, item))]
+    if len(real_sinks) == 1:
+        return _safe_title(f"计算「{_node_label(graph, geometry, real_sinks[0])}」"), "local_algorithm_sink"
+    return None, None
+
+
+def _node_label(graph, geometry, node_id: str) -> str:
+    title = str(getattr(geometry.get(node_id), "node_title", "") or "").strip()
+    if title:
+        return title
+    node = graph.node_by_id(node_id)
+    if node is None:
+        return ""
+    return re.sub(r"Node$", "", node.type_name.rsplit(".", 1)[-1]).strip()
+
+
+def _meaningful_label(value: str) -> bool:
+    return bool(value.strip()) and value.strip().lower() not in {
+        "node", "input", "output", "function", "property", "comment", "group",
+    }
+
+
+def _safe_title(value: str) -> str:
+    return value.replace(";", "，").replace("\r", " ").replace("\n", " ")[:4096]
+
+
+def _id_key(value: str):
+    return (0, int(value)) if value.lstrip("-").isdigit() else (1, value)

asecli/core/commentary.py

@@ -0,0 +1,225 @@
+"""Native ASE CommentaryNode inspection and semantic grouping."""
+
+from __future__ import annotations
+
+from .graph_ops import next_free_node_id
+from .model import AseGraph, NodeLine
+
+
+COMMENTARY_TYPE = "AmplifyShaderEditor.CommentaryNode"
+DEFAULT_NODE_WIDTH = 200.0
+DEFAULT_NODE_HEIGHT = 120.0
+NodeBounds = tuple[float, float, float, float]
+
+
+def parse_commentary_node(node: NodeLine) -> dict:
+    """Decode the variable-length ASE 1.9.6.2 CommentaryNode payload."""
+    if node.type_name != COMMENTARY_TYPE:
+        raise ValueError(f"node {node.node_id} is not a CommentaryNode")
+    fields = node.raw_fields
+    if len(fields) < 14:
+        raise ValueError(f"CommentaryNode {node.node_id} has too few serialized fields")
+    try:
+        width = float(fields[6])
+        height = float(fields[7])
+        count = int(fields[9])
+    except ValueError as exc:
+        raise ValueError(f"CommentaryNode {node.node_id} has invalid size or member count") from exc
+    if count < 0 or len(fields) != 14 + count:
+        raise ValueError(f"CommentaryNode {node.node_id} member count does not match its payload")
+    members = fields[10 : 10 + count]
+    if len(set(members)) != len(members):
+        raise ValueError(f"CommentaryNode {node.node_id} contains duplicate member ids")
+    x, y = _position(node)
+    if width <= 0 or height <= 0:
+        raise ValueError(f"CommentaryNode {node.node_id} must have positive width and height")
+    return {
+        "node_id": node.node_id,
+        "position": {"x": x, "y": y},
+        "width": width,
+        "height": height,
+        "note": fields[8],
+        "members": members,
+        "title": fields[10 + count],
+        "color": fields[11 + count],
+    }
+
+
+def inspect_comment_groups(graph: AseGraph) -> list[dict]:
+    return [parse_commentary_node(node) for node in graph.nodes if node.type_name == COMMENTARY_TYPE]
+
+
+def create_comment_group(
+    graph: AseGraph,
+    member_ids: list[str],
+    title: str,
+    *,
+    note: str = "Comment",
+    padding: float = 50.0,
+    node_id: int | None = None,
+    node_bounds: dict[str, NodeBounds] | None = None,
+) -> dict:
+    """Create one native Comment frame around nodes without moving them or their wires."""
+    _require_supported_graph(graph)
+    _validate_text(title, "title", allow_empty=False)
+    _validate_text(note, "note", allow_empty=True)
+    if not member_ids:
+        raise ValueError("a comment group requires at least one member node")
+    normalized = [str(value) for value in member_ids]
+    if len(set(normalized)) != len(normalized):
+        raise ValueError("comment group member ids must be unique")
+    if not 0 <= padding <= 1000:
+        raise ValueError("padding must be between 0 and 1000")
+
+    members: list[NodeLine] = []
+    for member_id in normalized:
+        member = graph.node_by_id(member_id)
+        if member is None:
+            raise KeyError(f"node {member_id} not found")
+        members.append(member)
+
+    new_id = next_free_node_id(graph) if node_id is None else node_id
+    if new_id < 0 or graph.node_by_id(str(new_id)) is not None:
+        raise ValueError(f"comment node id {new_id} is invalid or already exists")
+    if str(new_id) in normalized:
+        raise ValueError("a comment group cannot contain itself")
+    _validate_membership(graph, normalized)
+
+    bounds = [_node_bounds(node, node_bounds) for node in members]
+    min_x = min(item[0] for item in bounds)
+    min_y = min(item[1] for item in bounds)
+    max_x = max(item[2] for item in bounds)
+    max_y = max(item[3] for item in bounds)
+    x = min_x - padding
+    y = min_y - padding
+    width = max(100.0, max_x - min_x + 2 * padding)
+    height = max(100.0, max_y - min_y + 2 * padding)
+    fields = [
+        "Node", COMMENTARY_TYPE, str(new_id), f"{_number(x)},{_number(y)}", "Inherit", "False",
+        _number(width), _number(height), note, str(len(normalized)), *normalized,
+        title, "1,1,1,1", "0", "0",
+    ]
+    node = NodeLine(type_name=COMMENTARY_TYPE, node_id=str(new_id), raw_fields=fields)
+    _validate_new_group_overlap(graph, node, normalized)
+    graph.add_node(node)
+    return parse_commentary_node(node)
+
+
+def _validate_membership(graph: AseGraph, member_ids: list[str]) -> None:
+    groups = inspect_comment_groups(graph)
+    parent_of: dict[str, str] = {}
+    children: dict[str, list[str]] = {}
+    for group in groups:
+        children[group["node_id"]] = group["members"]
+        for member_id in group["members"]:
+            if member_id in parent_of:
+                raise ValueError(f"node {member_id} already belongs to multiple comment groups")
+            parent_of[member_id] = group["node_id"]
+    selected = set(member_ids)
+    for member_id in member_ids:
+        stack = list(children.get(member_id, []))
+        visited: set[str] = set()
+        while stack:
+            descendant = stack.pop()
+            if descendant in visited:
+                raise ValueError("existing comment groups contain a membership cycle")
+            visited.add(descendant)
+            if descendant in selected:
+                raise ValueError("select a nested comment frame or its children, not both")
+            stack.extend(children.get(descendant, []))
+    for member_id in member_ids:
+        if member_id in parent_of:
+            raise ValueError(f"node {member_id} already belongs to comment group {parent_of[member_id]}")
+
+
+def _node_bounds(
+    node: NodeLine,
+    measured: dict[str, NodeBounds] | None = None,
+) -> NodeBounds:
+    if measured is not None and node.node_id in measured and node.type_name != COMMENTARY_TYPE:
+        x, y, width, height = measured[node.node_id]
+        if width < 0 or height < 0:
+            raise ValueError(f"node {node.node_id} has invalid measured bounds")
+        return x, y, x + width, y + height
+    x, y = _position(node)
+    if node.type_name == COMMENTARY_TYPE:
+        group = parse_commentary_node(node)
+        width, height = group["width"], group["height"]
+    else:
+        width, height = DEFAULT_NODE_WIDTH, DEFAULT_NODE_HEIGHT
+    return x, y, x + width, y + height
+
+
+def _rect_overlap(
+    left: NodeBounds,
+    right: NodeBounds,
+    *,
+    tolerance: float = 0.01,
+) -> dict[str, float] | None:
+    overlap_left = max(left[0], right[0])
+    overlap_top = max(left[1], right[1])
+    width = min(left[2], right[2]) - overlap_left
+    height = min(left[3], right[3]) - overlap_top
+    if width <= tolerance or height <= tolerance:
+        return None
+    return {
+        "x": round(overlap_left, 3),
+        "y": round(overlap_top, 3),
+        "width": round(width, 3),
+        "height": round(height, 3),
+    }
+
+
+def _validate_new_group_overlap(graph: AseGraph, candidate: NodeLine, member_ids: list[str]) -> None:
+    """Reject partial/sibling overlap while allowing explicit full-containment nesting."""
+    groups = {group["node_id"]: group for group in inspect_comment_groups(graph)}
+    allowed_nested: set[str] = set()
+    stack = [member_id for member_id in member_ids if member_id in groups]
+    while stack:
+        group_id = stack.pop()
+        if group_id in allowed_nested:
+            continue
+        allowed_nested.add(group_id)
+        stack.extend(member_id for member_id in groups[group_id]["members"] if member_id in groups)
+
+    candidate_bounds = _node_bounds(candidate)
+    for group_id in sorted(groups, key=lambda value: (0, int(value)) if value.lstrip("-").isdigit() else (1, value)):
+        if group_id in allowed_nested:
+            continue
+        existing = graph.node_by_id(group_id)
+        assert existing is not None
+        overlap = _rect_overlap(candidate_bounds, _node_bounds(existing))
+        if overlap is not None:
+            raise ValueError(f"comment group would overlap unrelated comment group {group_id}")
+
+
+def _position(node: NodeLine) -> tuple[float, float]:
+    try:
+        x_raw, y_raw = node.raw_fields[3].split(",")
+        return float(x_raw), float(y_raw)
+    except (IndexError, ValueError) as exc:
+        raise ValueError(f"node {node.node_id} has invalid x,y position") from exc
+
+
+def _validate_text(value: str, label: str, *, allow_empty: bool) -> None:
+    if not isinstance(value, str):
+        raise ValueError(f"comment {label} must be a string")
+    if len(value) > 4096:
+        raise ValueError(f"comment {label} must not exceed 4096 characters")
+    if any(char in value for char in (";", "\r", "\n")):
+        raise ValueError(f"comment {label} contains a forbidden serialization character")
+    if not allow_empty and not value.strip():
+        raise ValueError(f"comment {label} must not be empty")
+
+
+def _require_supported_graph(graph: AseGraph) -> None:
+    try:
+        version = int(graph.version)
+    except ValueError as exc:
+        raise ValueError(f"unsupported non-numeric ASE graph version: {graph.version!r}") from exc
+    if version <= 12002:
+        raise ValueError(f"graph version {graph.version} predates the supported CommentaryNode format")
+
+
+def _number(value: float) -> str:
+    return str(int(value)) if value.is_integer() else format(value, ".6g")

asecli/core/compiled_metadata.py

@@ -0,0 +1,135 @@
+"""Post-ASE synchronization for managed ShaderLab property metadata."""
+
+from __future__ import annotations
+
+import re
+
+from .custom_gui import (
+    MANAGED_PROPERTY_METADATA_ATTRIBUTE_TYPES,
+    PROPERTY_METADATA_ATTRIBUTE_TYPES,
+    is_material_property_node,
+    parse_property_metadata_attribute,
+    read_property_metadata_tail,
+)
+from .compiled_properties import inspect_compiled_properties
+from .model import AseFile
+
+
+_MANAGED_ATTRIBUTE_TYPES = frozenset(
+    MANAGED_PROPERTY_METADATA_ATTRIBUTE_TYPES
+)
+_KNOWN_TEMPLATE_COMPILED_ONLY_PROPERTIES = {
+    "2992e84f91cbeb14eab234972e07ea9d": frozenset({
+        "_TessPhongStrength",
+        "_TessValue",
+        "_TessMin",
+        "_TessMax",
+        "_TessEdgeLength",
+        "_TessMaxDisp",
+    }),
+}
+
+
+def hide_known_template_compiled_only_properties(
+    ase_file: AseFile, template_guid: str
+) -> list[dict]:
+    """Hide exact, versioned template controls that have no graph PropertyNode.
+
+    Unknown compiled-only properties remain visible so the presentation
+    contract can reject them instead of silently hiding user-owned data.
+    """
+    compiled, error = inspect_compiled_properties(ase_file.prefix)
+    if error is not None:
+        raise ValueError(f"compiled ShaderLab properties are unavailable: {error}")
+    known = _KNOWN_TEMPLATE_COMPILED_ONLY_PROPERTIES.get(template_guid, frozenset())
+    graph_names = {
+        node.raw_fields[7]
+        for node in ase_file.graph.nodes
+        if is_material_property_node(node)
+    }
+    changes: list[dict] = []
+    prefix = ase_file.prefix
+    for prop in compiled:
+        property_name = prop["property_name"]
+        if prop["hidden"] or property_name in graph_names or property_name not in known:
+            continue
+        pattern = re.compile(
+            rf"(?m)^(?P<indent>[ \t]*)(?P<attributes>(?:\[[^\]\r\n]*\][ \t]*)*)"
+            rf"(?P<name>{re.escape(property_name)})(?P<suffix>[ \t]*\()"
+        )
+        matches = list(pattern.finditer(prefix))
+        if len(matches) != 1:
+            raise ValueError(
+                f"expected one compiled ShaderLab declaration for {property_name!r}, found {len(matches)}"
+            )
+        match = matches[0]
+        replacement = (
+            match.group("indent")
+            + "[HideInInspector] "
+            + match.group("attributes")
+            + match.group("name")
+            + match.group("suffix")
+        )
+        prefix = prefix[: match.start()] + replacement + prefix[match.end() :]
+        changes.append({
+            "kind": "compiled_template_property_hidden",
+            "property_name": property_name,
+            "template_guid": template_guid,
+        })
+    ase_file.prefix = prefix
+    return changes
+
+
+def sync_compiled_property_metadata(ase_file: AseFile) -> list[dict]:
+    """Mirror graph metadata into compiled properties after an ASE save.
+
+    Some editor builds discard custom PropertyNode attributes while saving.
+    Unity's ShaderGUI reads decorators from the compiled ``Properties`` block,
+    so restore the managed attributes there while preserving unrelated ones.
+    """
+    changes: list[dict] = []
+    prefix = ase_file.prefix
+    for node in ase_file.graph.nodes:
+        if not is_material_property_node(node):
+            continue
+        property_name = node.raw_fields[7]
+        tail = read_property_metadata_tail(ase_file.graph, node)
+        managed = [
+            raw for raw in tail.attributes
+            if parse_property_metadata_attribute(raw)["type"] in _MANAGED_ATTRIBUTE_TYPES
+        ]
+        pattern = re.compile(
+            rf"(?m)^(?P<indent>[ \t]*)(?P<attributes>(?:\[[^\]\r\n]*\][ \t]*)*)"
+            rf"(?P<name>{re.escape(property_name)})(?P<suffix>[ \t]*\()"
+        )
+        matches = list(pattern.finditer(prefix))
+        if len(matches) != 1:
+            raise ValueError(
+                f"expected one compiled ShaderLab declaration for {property_name!r}, found {len(matches)}"
+            )
+        match = matches[0]
+        existing = re.findall(r"\[[^\]\r\n]*\]", match.group("attributes"))
+        preserved = [raw for raw in existing if not _is_managed(raw)]
+        attributes = [*preserved, *managed]
+        replacement = (
+            match.group("indent")
+            + ((" ".join(attributes) + " ") if attributes else "")
+            + match.group("name")
+            + match.group("suffix")
+        )
+        if match.group(0) == replacement:
+            continue
+        prefix = prefix[: match.start()] + replacement + prefix[match.end() :]
+        changes.append({
+            "kind": "compiled_property_metadata", "node_id": node.node_id,
+            "property_name": property_name, "before": existing, "after": attributes,
+        })
+    ase_file.prefix = prefix
+    return changes
+
+
+def _is_managed(raw: str) -> bool:
+    try:
+        return parse_property_metadata_attribute(raw)["type"] in _MANAGED_ATTRIBUTE_TYPES
+    except ValueError:
+        return False