asecli 0.6.2__py3-none-any.whl

asecli/checks/usage.py

@@ -0,0 +1,141 @@
+"""Conservative graph-liveness and external material-property usage audit."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from pathlib import Path
+import re
+
+from ..core import AseGraph, NodeLine, is_material_property_node, local_var_edges
+
+
+COMMENTARY_TYPE = "AmplifyShaderEditor.CommentaryNode"
+MASTER_TYPES = {
+    "AmplifyShaderEditor.TemplateMultiPassMasterNode",
+    "AmplifyShaderEditor.TemplateMasterNode",
+    "AmplifyShaderEditor.StandardSurfaceOutputNode",
+    "AmplifyShaderEditor.FunctionOutput",
+    "AmplifyShaderEditor.FunctionOutputNode",
+}
+SOURCE_SUFFIXES = {".cs", ".cginc", ".hlsl", ".compute", ".shader"}
+MAX_SCAN_BYTES = 8 * 1024 * 1024
+
+
+def live_node_ids(graph: AseGraph) -> set[str]:
+    """Return nodes that contribute to an output through wires or Local Vars."""
+    reverse: dict[str, set[str]] = defaultdict(set)
+    for wire in graph.wires:
+        reverse[wire.in_node].add(wire.out_node)
+    for source, target in local_var_edges(graph):
+        reverse[target].add(source)
+
+    masters = [node for node in graph.nodes if node.type_name in MASTER_TYPES]
+    active = [
+        node.node_id
+        for node in masters
+        if len(node.raw_fields) > 6 and node.raw_fields[6].lower() == "true"
+    ]
+    sinks = active or [node.node_id for node in masters]
+    live = set(sinks)
+    queue = deque(sinks)
+    while queue:
+        node_id = queue.popleft()
+        for source in reverse.get(node_id, ()):
+            if source in live:
+                continue
+            live.add(source)
+            queue.append(source)
+    return live
+
+
+def usage_audit(shader_path: str, graph: AseGraph) -> dict:
+    """Classify dead-graph candidates without calling externally used properties unused."""
+    live = live_node_ids(graph)
+    connected = {
+        node_id
+        for wire in graph.wires
+        for node_id in (wire.out_node, wire.in_node)
+    }
+    semantic = {node_id for edge in local_var_edges(graph) for node_id in edge}
+    project_root = _detect_project_root(Path(shader_path).resolve())
+    unused: list[dict] = []
+    external: list[dict] = []
+    for node in graph.nodes:
+        if node.node_id in live or node.type_name == COMMENTARY_TYPE or node.type_name in MASTER_TYPES:
+            continue
+        item = {
+            "node_id": node.node_id,
+            "node_type": node.type_name,
+            "position": node.raw_fields[3] if len(node.raw_fields) > 3 else None,
+            "reason": "not_reachable_from_graph_output",
+            "has_wire_or_local_var_relation": node.node_id in connected or node.node_id in semantic,
+        }
+        if is_material_property_node(node):
+            property_name = node.raw_fields[7]
+            item["property_name"] = property_name
+            refs = find_external_references(project_root, Path(shader_path).resolve(), property_name)
+            if refs:
+                item["classification"] = "external_consumer"
+                item["external_references"] = refs
+                external.append(item)
+                continue
+        item["classification"] = "unused_candidate"
+        unused.append(item)
+    return {
+        "live_node_count": len(live),
+        "live_node_ids": sorted(live, key=_node_id_sort_key),
+        "unused_candidates": sorted(unused, key=lambda item: _node_id_sort_key(item["node_id"])),
+        "external_consumers": sorted(external, key=lambda item: _node_id_sort_key(item["node_id"])),
+        "policy": (
+            "unused_candidates are conservative review targets; external_consumers must not be pruned "
+            "only because they have no ASE wire"
+        ),
+    }
+
+
+def external_references_for_node(shader_path: str, node: NodeLine) -> list[dict]:
+    if not is_material_property_node(node):
+        return []
+    path = Path(shader_path).resolve()
+    return find_external_references(_detect_project_root(path), path, node.raw_fields[7])
+
+
+def find_external_references(project_root: Path, shader_path: Path, token: str) -> list[dict]:
+    pattern = re.compile(rf"(?<![A-Za-z0-9_]){re.escape(token)}(?![A-Za-z0-9_])")
+    results: list[dict] = []
+    assets = project_root / "Assets"
+    for path in sorted(assets.rglob("*")):
+        if not path.is_file() or path.is_symlink() or path.resolve() == shader_path:
+            continue
+        if path.suffix.lower() not in SOURCE_SUFFIXES or path.name.endswith(".shader.bak"):
+            continue
+        try:
+            if path.stat().st_size > MAX_SCAN_BYTES:
+                continue
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for line_number, line in enumerate(text.splitlines(), 1):
+            if pattern.search(line):
+                results.append(
+                    {
+                        "path": path.relative_to(project_root).as_posix(),
+                        "line": line_number,
+                    }
+                )
+                if len(results) >= 100:
+                    return results
+    return results
+
+
+def _detect_project_root(path: Path) -> Path:
+    cur = path.parent
+    while cur != cur.parent:
+        if (cur / "Assets").is_dir() and (cur / "ProjectSettings").is_dir():
+            return cur
+        cur = cur.parent
+    raise ValueError(f"cannot locate Unity project root for {path}")
+
+
+def _node_id_sort_key(value: str) -> tuple[int, int | str]:
+    return (0, int(value)) if value.lstrip("-").isdigit() else (1, value)

asecli/checks/validate.py

@@ -0,0 +1,129 @@
+"""Structural validation (TASK-0008)."""
+
+from __future__ import annotations
+
+from ..core import (
+    AseFile,
+    COMMENTARY_TYPE,
+    parse_commentary_node,
+)
+from .checksum import ChecksumFormatError, verify_checksum
+from .local_vars import append_local_var_issues
+
+
+def validate_file(ase_file: AseFile) -> list[dict]:
+    """Return a list of issue dicts. Empty list means the graph is structurally sound."""
+    issues: list[dict] = []
+    graph = ase_file.graph
+
+    seen: dict[str, int] = {}
+    for n in graph.nodes:
+        seen[n.node_id] = seen.get(n.node_id, 0) + 1
+    for node_id, count in seen.items():
+        if count > 1:
+            issues.append(
+                {"code": "DUPLICATE_NODE_ID", "severity": "error", "node_id": node_id,
+                 "message": f"node id {node_id} appears {count} times"}
+            )
+
+    node_ids = set(seen)
+    input_sources: dict[tuple[str, str], list[tuple[str, str]]] = {}
+    for w in graph.wires:
+        if w.in_node not in node_ids:
+            issues.append(
+                {"code": "DANGLING_WIRE", "severity": "error", "node_id": w.in_node,
+                 "message": f"wire references missing input node {w.in_node}"}
+            )
+        if w.out_node not in node_ids:
+            issues.append(
+                {"code": "DANGLING_WIRE", "severity": "error", "node_id": w.out_node,
+                 "message": f"wire references missing output node {w.out_node}"}
+            )
+        input_sources.setdefault((w.in_node, w.in_port), []).append((w.out_node, w.out_port))
+
+    for (node_id, port), sources in input_sources.items():
+        unique_sources = sorted(set(sources))
+        if len(unique_sources) > 1:
+            rendered = ", ".join(f"{node}:{source_port}" for node, source_port in unique_sources)
+            issues.append(
+                {
+                    "code": "MULTIPLE_INPUT_CONNECTIONS",
+                    "severity": "error",
+                    "node_id": node_id,
+                    "port": port,
+                    "message": f"input {node_id}:{port} has multiple sources: {rendered}",
+                }
+            )
+
+    for n in graph.nodes:
+        if not n.type_name:
+            issues.append(
+                {"code": "MALFORMED_NODE", "severity": "error", "node_id": n.node_id,
+                 "message": f"node {n.node_id} has empty type"}
+            )
+
+    append_local_var_issues(graph, issues)
+
+    comment_children: dict[str, list[str]] = {}
+    comment_parent: dict[str, str] = {}
+    for n in graph.nodes:
+        if n.type_name != COMMENTARY_TYPE:
+            continue
+        try:
+            group = parse_commentary_node(n)
+        except ValueError as exc:
+            issues.append(
+                {"code": "MALFORMED_COMMENT", "severity": "error", "node_id": n.node_id,
+                 "message": str(exc)}
+            )
+            continue
+        comment_children[n.node_id] = [member for member in group["members"] if member in node_ids]
+        for member in group["members"]:
+            if member not in node_ids:
+                issues.append(
+                    {"code": "DANGLING_COMMENT_MEMBER", "severity": "error", "node_id": n.node_id,
+                     "message": f"comment {n.node_id} references missing member node {member}"}
+                )
+            elif member in comment_parent:
+                issues.append(
+                    {"code": "MULTIPLE_COMMENT_PARENTS", "severity": "error", "node_id": member,
+                     "message": f"node {member} belongs to comments {comment_parent[member]} and {n.node_id}"}
+                )
+            else:
+                comment_parent[member] = n.node_id
+
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit_comment(node_id: str) -> None:
+        if node_id in visiting:
+            issues.append(
+                {"code": "COMMENT_MEMBERSHIP_CYCLE", "severity": "error", "node_id": node_id,
+                 "message": f"comment membership contains a cycle at node {node_id}"}
+            )
+            return
+        if node_id in visited:
+            return
+        visiting.add(node_id)
+        for member in comment_children.get(node_id, []):
+            if member in comment_children:
+                visit_comment(member)
+        visiting.remove(node_id)
+        visited.add(node_id)
+
+    for comment_id in comment_children:
+        visit_comment(comment_id)
+
+    try:
+        ok, stored, actual = verify_checksum(ase_file.serialize())
+    except ChecksumFormatError as exc:
+        issues.append(
+            {"code": "CHECKSUM_FORMAT", "severity": "error", "message": str(exc)}
+        )
+        return issues
+    if stored is not None and not ok:
+        issues.append(
+            {"code": "CHECKSUM_MISMATCH", "severity": "warning",
+             "message": f"stored {stored} != computed {actual} (non-blocking: ASE loads anyway)"}
+        )
+    return issues

asecli/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI composition root (TASK-0010 wires the JSON contract here)."""

asecli/cli/commands.py

@@ -0,0 +1,237 @@
+"""Command implementations (TASK-0010). Split from main.py for LOC budget."""
+
+from __future__ import annotations
+
+import os
+
+from ..bridge import McpError
+from ..bridge import recompile_via_mcp
+from ..checks import (
+    ChecksumFormatError,
+    fix_checksum,
+    validate_file,
+    verify_checksum,
+)
+from ..core import (
+    AseFile,
+    NodeLine,
+    connect,
+    disconnect,
+    node_from_schema,
+    parse_node_line,
+    require_managed_property_presentation,
+    set_node_field,
+)
+from ..schema import allows_mutation, is_version_compatible, schema_for, schema_version
+from .io import (
+    UnsafeWritePathError,
+    WriteConflictError,
+    atomic_write,
+    read_text_snapshot,
+)
+from .recompile_metadata import restore_recompile_metadata, snapshot_recompile_metadata
+
+EXIT_OK = 0
+EXIT_ERROR = 2
+EXIT_BRIDGE = 3
+class CliError(Exception):
+    def __init__(self, code: str, message: str, data: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.data = data
+def _load(path: str) -> AseFile:
+    try:
+        return AseFile.from_path(path)
+    except FileNotFoundError:
+        raise CliError("NOT_FOUND", f"file not found: {path}")
+    except ValueError as e:
+        raise CliError("PARSE_ERROR", str(e))
+
+
+def _save(ase_file: AseFile, path: str, write: bool) -> dict:
+    issues = validate_file(ase_file)
+    errors = [issue for issue in issues if issue["severity"] == "error"]
+    if errors:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"mutation would leave {len(errors)} structural error(s)",
+            {"issues": issues, "error_count": len(errors)},
+        )
+    if not write:
+        return {"written": False, "preview_bytes": len(ase_file.serialize())}
+    try:
+        require_managed_property_presentation(ase_file)
+    except ValueError as exc:
+        raise CliError("PROPERTY_PRESENTATION_ERROR", str(exc)) from exc
+    _commit_text(path, ase_file.serialize(), ase_file.source_digest)
+    return {"written": True, "path": str(path)}
+
+
+def _commit_text(path: str, text: str, expected_digest: str | None) -> None:
+    try:
+        atomic_write(path, text, expected_digest=expected_digest)
+    except WriteConflictError as exc:
+        raise CliError(
+            "WRITE_CONFLICT",
+            str(exc),
+            {
+                "path": str(exc.path),
+                "expected": exc.expected[:12] if exc.expected else None,
+                "actual": exc.actual[:12] if exc.actual else None,
+            },
+        ) from exc
+    except UnsafeWritePathError as exc:
+        raise CliError("UNSAFE_PATH", str(exc)) from exc
+    except OSError as exc:
+        raise CliError("WRITE_ERROR", str(exc)) from exc
+
+
+def _parse_endpoint(ep: str) -> tuple[str, str]:
+    if ":" not in ep:
+        raise CliError("USAGE_ERROR", f"endpoint must be node:port, got {ep!r}")
+    node, port = ep.split(":", 1)
+    return node, port
+
+
+def cmd_parse(args) -> dict:
+    f = _load(args.file)
+    g = f.graph
+    return {
+        "file": args.file,
+        "version": g.version,
+        "node_count": len(g.nodes),
+        "wire_count": len(g.wires),
+        "nodes": [{"id": n.node_id, "type": n.type_name, "pos": n.raw_fields[3]} for n in g.nodes],
+    }
+
+
+def cmd_set_field(args) -> dict:
+    f = _load(args.file)
+    try:
+        node = set_node_field(f.graph, args.node, args.field, args.value)
+    except (KeyError, IndexError) as e:
+        raise CliError("NOT_FOUND", str(e))
+    except ValueError as e:
+        raise CliError("USAGE_ERROR", str(e))
+    saved = _save(f, args.file, args.write)
+    return {"node": node.node_id, "field": args.field, "value": args.value, **saved}
+
+
+def cmd_add_node(args) -> dict:
+    f = _load(args.file)
+    if args.line is not None:
+        parse_node_line(args.line)
+        fields = args.line.split(";")
+        node = NodeLine(type_name=fields[1], node_id=fields[2], raw_fields=fields)
+    else:
+        if not args.type:
+            raise CliError("USAGE_ERROR", "either --type or --line is required")
+        s = schema_for(args.type)
+        if s is None:
+            raise CliError("SCHEMA_UNAVAILABLE", f"unknown node type: {args.type} (use --line to insert raw)")
+        if not allows_mutation(args.type):
+            raise CliError("SCHEMA_UNAVAILABLE", f"{args.type} has opaque layout; use --line with a real serialized line")
+        if not is_version_compatible(args.type, f.graph.version):
+            raise CliError(
+                "SCHEMA_VERSION_MISMATCH",
+                f"node schema version {schema_version(args.type)} is not compatible with graph version {f.graph.version}",
+            )
+        node = node_from_schema(f.graph, s, args.id, args.pos, args.type)
+    try:
+        f.graph.add_node(node)
+    except ValueError as e:
+        raise CliError("VALIDATION_ERROR", str(e))
+    saved = _save(f, args.file, args.write)
+    import re as _re
+
+    warnings = []
+    if _re.search(r"[0-9a-f]{32}", node.to_line(), _re.IGNORECASE):
+        warnings.append(
+            "node line contains a 32-hex identifier copied from the schema placeholder; "
+            "verify uniqueness in Unity (duplicate guids may conflict)"
+        )
+    return {"node_id": node.node_id, "type": node.type_name, "warnings": warnings, **saved}
+
+
+def cmd_connect(args) -> dict:
+    f = _load(args.file)
+    src, sport = _parse_endpoint(args.src)
+    dst, dport = _parse_endpoint(args.dst)
+    try:
+        wire = connect(f.graph, src, sport, dst, dport)
+    except KeyError as e:
+        raise CliError("NOT_FOUND", str(e))
+    except ValueError as e:
+        raise CliError("USAGE_ERROR", str(e))
+    saved = _save(f, args.file, args.write)
+    return {"from": args.src, "to": args.dst, "line": wire.to_line(), **saved}
+
+
+def cmd_disconnect(args) -> dict:
+    f = _load(args.file)
+    src, sport = _parse_endpoint(args.src)
+    dst, dport = _parse_endpoint(args.dst)
+    if not disconnect(f.graph, src, sport, dst, dport):
+        raise CliError("NOT_FOUND", f"wire {args.src} -> {args.dst} not found")
+    saved = _save(f, args.file, args.write)
+    return {"removed": True, **saved}
+
+
+def cmd_validate(args) -> dict:
+    f = _load(args.file)
+    issues = validate_file(f)
+    data = {
+        "file": args.file,
+        "issues": issues,
+        "error_count": sum(1 for i in issues if i["severity"] == "error"),
+    }
+    if data["error_count"]:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"graph contains {data['error_count']} structural error(s)",
+            data,
+        )
+    return data
+
+
+def cmd_fix_checksum(args) -> dict:
+    try:
+        text, source_digest = read_text_snapshot(args.file)
+    except FileNotFoundError:
+        raise CliError("NOT_FOUND", f"file not found: {args.file}")
+    except UnsafeWritePathError as exc:
+        raise CliError("UNSAFE_PATH", str(exc)) from exc
+    try:
+        ok, stored, actual = verify_checksum(text)
+        fixed = fix_checksum(text)
+    except ChecksumFormatError as exc:
+        raise CliError("CHECKSUM_FORMAT_ERROR", str(exc)) from exc
+    if args.write:
+        _commit_text(args.file, fixed, source_digest)
+    return {"was_valid": ok, "stored": stored, "fixed_to": actual, "written": bool(args.write)}
+
+
+def cmd_recompile(args) -> dict:
+    if args.instance_token_argv is not None:
+        raise CliError("USAGE_ERROR", "do not pass MCP tokens via argv; use ASECLI_MCP_INSTANCE_TOKEN")
+    instance_token = os.environ.get("ASECLI_MCP_INSTANCE_TOKEN")
+    metadata_snapshot = snapshot_recompile_metadata(args.file)
+    try:
+        result = recompile_via_mcp(
+            args.file,
+            mcp_url=args.mcp_url,
+            instance_token=instance_token,
+            allow_remote_mcp=args.allow_remote_mcp,
+        )
+        if metadata_snapshot:
+            ase_file, restored = restore_recompile_metadata(args.file, metadata_snapshot)
+            output = fix_checksum(ase_file.serialize())
+            _commit_text(args.file, output, ase_file.source_digest)
+            result["metadata_restored"] = restored
+        return result
+    except McpError as e:
+        raise CliError("BRIDGE_ERROR", str(e), e.data)
+    except FileNotFoundError as e:
+        raise CliError("NOT_FOUND", str(e))
+    except ValueError as e:
+        raise CliError("USAGE_ERROR", str(e))

asecli/cli/commentary_command.py

@@ -0,0 +1,158 @@
+"""CLI composition for native ASE Comment-frame grouping."""
+
+from __future__ import annotations
+
+import os
+
+from ..bridge import McpError, measure_node_bounds_via_mcp
+from ..checks import fix_checksum, validate_file
+from ..core import (
+    comment_containment_issues,
+    create_comment_group,
+    inspect_comment_groups,
+    refit_comment_groups,
+)
+from .commands import CliError, _commit_text, _load
+
+
+def cmd_comment_group(args) -> dict:
+    f = _load(args.file)
+    if args.fit:
+        if args.nodes is not None or args.title is not None or args.note is not None or args.id is not None:
+            raise CliError("USAGE_ERROR", "--fit cannot be combined with Comment creation options")
+        bounds = _editor_bounds(args)
+        try:
+            before = comment_containment_issues(f.graph, bounds)
+            changes = refit_comment_groups(
+                f.graph,
+                bounds,
+                padding=50.0 if args.padding is None else args.padding,
+            )
+            after = comment_containment_issues(f.graph, bounds)
+        except KeyError as exc:
+            raise CliError("NOT_FOUND", str(exc))
+        except ValueError as exc:
+            raise CliError("COMMENT_GROUP_ERROR", str(exc))
+        overlaps = [issue for issue in after if issue["code"] == "COMMENT_GROUP_OVERLAP"]
+        if args.write and overlaps:
+            raise CliError(
+                "COMMENT_GROUP_ERROR",
+                f"fit would leave {len(overlaps)} unrelated Comment group overlap(s); move groups apart first",
+                {"issues": overlaps, "error_count": len(overlaps)},
+            )
+        output = _validated_output(f)
+        if args.write:
+            _commit_text(args.file, output, f.source_digest)
+        return {
+            "file": args.file,
+            "action": "fit",
+            "measurement": "live_ase_true_position",
+            "padding": 50.0 if args.padding is None else args.padding,
+            "changes": changes,
+            "changed_count": len(changes),
+            "before_issues": before,
+            "after_issues": after,
+            "written": bool(args.write),
+            "path": args.file if args.write else None,
+            "preview_bytes": len(output),
+            "checksum_recomputed": True,
+            "requires_editor_reload": True,
+            "structural_validation": "passed",
+            "visual_validation": "pending",
+        }
+
+    if args.nodes is None:
+        if any((args.title is not None, args.note is not None, args.padding is not None,
+                args.id is not None, args.write, args.editor_bounds)):
+            raise CliError("USAGE_ERROR", "--nodes and --title are required to create a comment group")
+        try:
+            groups = inspect_comment_groups(f.graph)
+        except ValueError as exc:
+            raise CliError("COMMENT_GROUP_ERROR", str(exc))
+        data = {
+            "file": args.file,
+            "action": "inspect",
+            "groups": groups,
+            "written": False,
+            "structural_validation": "passed",
+            "visual_validation": "pending",
+        }
+        if args.check_bounds:
+            bounds = _editor_bounds(args)
+            try:
+                data["measurement"] = "live_ase_true_position"
+                data["containment_issues"] = comment_containment_issues(f.graph, bounds)
+            except ValueError as exc:
+                raise CliError("COMMENT_GROUP_ERROR", str(exc))
+        return data
+    if args.title is None:
+        raise CliError("USAGE_ERROR", "--title is required with --nodes")
+    if args.check_bounds:
+        raise CliError("USAGE_ERROR", "--check-bounds cannot be combined with Comment creation")
+    member_ids = [item.strip() for item in args.nodes.split(",")]
+    if any(not item for item in member_ids):
+        raise CliError("USAGE_ERROR", "--nodes must be a comma-separated list of node ids")
+
+    bounds = _editor_bounds(args) if args.editor_bounds else None
+    try:
+        group = create_comment_group(
+            f.graph,
+            member_ids,
+            args.title,
+            note="Comment" if args.note is None else args.note,
+            padding=50.0 if args.padding is None else args.padding,
+            node_id=args.id,
+            node_bounds=bounds,
+        )
+    except KeyError as exc:
+        raise CliError("NOT_FOUND", str(exc))
+    except ValueError as exc:
+        raise CliError("COMMENT_GROUP_ERROR", str(exc))
+
+    output = _validated_output(f)
+    if args.write:
+        _commit_text(args.file, output, f.source_digest)
+    return {
+        "file": args.file,
+        "action": "create",
+        "group": group,
+        "written": bool(args.write),
+        "path": args.file if args.write else None,
+        "preview_bytes": len(output),
+        "checksum_recomputed": True,
+        "requires_editor_reload": True,
+        "measurement": "live_ase_true_position" if bounds is not None else "offline_estimate",
+        "structural_validation": "passed",
+        "visual_validation": "pending",
+    }
+
+
+def _editor_bounds(args) -> dict[str, tuple[float, float, float, float]]:
+    if args.instance_token_argv is not None:
+        raise CliError("USAGE_ERROR", "do not pass MCP tokens via argv; use ASECLI_MCP_INSTANCE_TOKEN")
+    try:
+        return measure_node_bounds_via_mcp(
+            args.file,
+            mcp_url=args.mcp_url,
+            instance_token=os.environ.get("ASECLI_MCP_INSTANCE_TOKEN"),
+            unity_instance=args.unity_instance,
+            allow_remote_mcp=args.allow_remote_mcp,
+        )
+    except McpError as exc:
+        raise CliError("BRIDGE_ERROR", str(exc), exc.data)
+    except FileNotFoundError as exc:
+        raise CliError("NOT_FOUND", str(exc))
+    except ValueError as exc:
+        raise CliError("USAGE_ERROR", str(exc))
+
+
+def _validated_output(f) -> str:
+    issues = validate_file(f)
+    errors = [issue for issue in issues if issue["severity"] == "error"]
+    if errors:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"mutation would leave {len(errors)} structural error(s)",
+            {"issues": issues, "error_count": len(errors)},
+        )
+    return fix_checksum(f.serialize())