sfsm-compare-json-uml-diagram

name	sfsm-compare-json-uml-diagram
description	Compare an SFSM FA definition JSON file against a draw.io UML state diagram and report every discrepancy. Use when validating that a diagram matches its source JSON, or vice versa. Combines drawio-to-json and compare-compact-jsons for round-trip verification.
metadata	{"author":"vsirotin","version":"2.0"}

Compare SFSM Compact JSON ↔ UML State Diagram (draw.io)

This skill validates the correspondence between an SFSM FA definition in compact JSON format and a draw.io UML state diagram. It combines two scripts to produce a detailed diff report without modifying either file:

1. drawio-to-json.js extracts JSON from the diagram (via SFSM metadata in cell styles or shape-based heuristics)
2. compare-compact-jsons.js performs an intelligent comparison of the original and extracted JSON

Usage

Use this skill when you need to:

• Validate that a draw.io diagram matches its source JSON (e.g., after generating it with sfsm-json-to-uml-diagram)
• Verify a round-trip workflow: JSON → Diagram → JSON → Compare
• Audit a manually edited diagram to detect any data loss or drift
• Catch discrepancies early (missing transitions, target mismatches, incorrect commands, etc.)

Workflow

The skill requests two file paths from you (unless you provide them upfront):

• JSON file: A compact-format SFSM definition
• Diagram file: A .drawio file (ideally generated by json-to-drawio.js)

It then runs:

1. drawio-to-json.js <diagram.drawio> <extracted.json> — extract JSON from the diagram
2. compare-compact-jsons.js <original.json> <extracted.json> — compare and report differences

Output

The comparison report shows, per FA:

• ✅ Number of matching transitions
• ❌ Missing transitions (in diagram, not in JSON)
• ❌ Extra transitions (in diagram, not in JSON)
• ❌ Mismatches (same from/signal pair, different to or command)

If both sides match exactly, the report confirms alignment with no discrepancies.

Input/Output

• Input: Compact JSON file path (requested if not provided) and diagram .drawio file path (requested if not provided)
• Output: A report printed to console (no files are modified)

Commands

cd ts/ts-stop
node scripts/drawio-to-json.js <input.drawio> <extracted.json>
node scripts/compare-compact-jsons.js <original.json> <extracted.json>

Important note

No files are modified by this skill. If the comparison reveals discrepancies and you decide which side is authoritative, use:

• sfsm-json-to-uml-diagram to regenerate the diagram from the JSON if the JSON is authoritative
• sfsm-uml-diagram-to-json to extract the diagram's corrected JSON if the diagram is authoritative

See 04-tools.md § 7.5.5 for detailed documentation.