spviz-difference-visualization

Files (1)

• SKILL.md

SKILL.md (first lines)

# Compare SPViz project model revisions
Use this skill for the current generated difference-visualization workflow.
It guides you through existing generated support.

## Preconditions
Establish the two models that should be compared first.
If necessary, generate the current one from the corresponding repository with the `spviz-model-generator` skill first before returning to this skill.
Both inputs must be project models conforming to the same A2M and readable by the generated language server.
Each one may be a generated XMI file or a project model DSL instance.

## The generated diff DSL
Unless the user passed `--no-diff` during SPViz generation, the A2M generation creates a generated diff DSL project. Its grammar is intentionally small:
`compare "before.osgi" to "after.osgi"`
The actual file extension is derived from the lower-case A2M name followed by `diff` (for example, an `OSGi` model uses `.osgidiff`).
Do not compare models generated by different extractor rules without reporting that the extractor change itself may account for differences.
Model paths must be relative to the diff file, do not use absolute paths.
Use forward-slash relative URI paths and quote them.

## Generate and build
If the generated visualization build does not include the `*.diffviz` and `*.diff.dsl` modules,
regenerate the project without the `--no-diff` flag with the `spviz-build` skill.

## Execute a comparison
Use `spviz-klighd-execution` to load a difference visualization file, it works the same way as normal model visualizations, but the diagram shows both contained models at the same time with different colors for additions, removals, and changes.

## Interpret the result
The source model is shown as the left side and the target model as the right side:
- elements present only in the source are highlighted as removals in red
- elements present only in the target are highlighted as additions in green
- changed elements are highlighted in both models in blue
Elements are matched solely by artifact type and `ecoreId`.
A matching element is highlighted as modified only when its directly contained artifacts or outgoing connections differ.
Changing an `ecoreId` appears as a removal and addition.
A moved element may not itself be highlighted when its own outgoing connections are unchanged, but its changed containers can be highlighted instead.
The comparison does not guarantee detection of arbitrary semantic equivalence.

From kieler/SoftwareProjectViz, EPL-2.0.

More from kieler/SoftwareProjectViz