Feat/diff by jdacoello · Pull Request #521 · COVESA/vss-tools

jdacoello · 2026-05-13T15:03:28Z

It implements two main things:

A compose command to take a snapshot of the model to persist a stand alone immutable state
A diff command to compare and report the differences between two snapshots

erikbosch · 2026-05-18T12:43:47Z

It is in "exporters" folder but it is not an exporter, or?

Good catch, I've just moved it to the parent directory.

erikbosch · 2026-05-18T13:08:29Z

+|---|---|---|
+| `model_snapshot.vspec` | The full model tree | Yes |
+| `structs_snapshot.vspec` | Custom struct type definitions | Only when `--types` is given |
+| `units_snapshot.yaml` | Resolved units | Only when units are provided |


A bit unsure on how to interpret "Only when units are provided". File also produced when using default unit file, see example below

.venv-vss) erik@vbox:~/vehicle_signal_specification$ vspec compose -s spec/VehicleSignalSpecification.vspec -o tmp [15:06:58] INFO Loaded 'VSSQuantity', file=/home/erik/vehicle_signal_specification/spec/quantities.yaml, elements=30 units_quantities.py:34 INFO Loaded 'VSSUnit', file=/home/erik/vehicle_signal_specification/spec/units.yaml, elements=69 units_quantities.py:34 INFO VSpecs loaded, amount=91 vspec.py:130 [15:06:59] INFO Composing vspec model into tmp... compose.py:124 INFO VSpecs loaded, amount=91 vspec.py:130 INFO Signal tree written to tmp/model_snapshot.vspec compose.py:135 INFO Loaded 'VSSUnit', file=/home/erik/vehicle_signal_specification/spec/units.yaml, elements=69 units_quantities.py:34 INFO Units written to tmp/units_snapshot.yaml compose.py:160 INFO Loaded 'VSSQuantity', file=/home/erik/vehicle_signal_specification/spec/quantities.yaml, elements=30 units_quantities.py:34 INFO Quantities written to tmp/quantities_snapshot.yaml

True. The reason for that is because the vss-tools have a fallback behavior if no units or quantity are explicitly passed. They read the default expected location for units and quantities. I updated the docs.

erikbosch · 2026-05-19T14:19:54Z

MoM:

D presented the PR
D will show demo next week
Please review
E: Shall we run compose for every release
D: Yes, shall be mandatory
E: We can look at that after the PR is merged
D: Would be good with a minor release after this is merged.
V: Wondering on automatic triggering

sschleemilch · 2026-05-20T08:55:24Z

-@click.group(context_settings={"auto_envvar_prefix": "vss_tools"}, invoke_without_command=True)
+@click.group(
+    cls=LazyGroup,
+    lazy_subcommands={


I don't think we need the lazy annotations here. Just make the commands "normal" ones by using @cli.command annotations for them

sschleemilch · 2026-05-20T08:55:56Z

+# output remains a valid, re-parseable vspec.
+SNAPSHOT_EXCLUDE_FIELDS = ["delete", "fqn", "is_instance"]
+
+MODEL_SNAPSHOT_FILENAME = "model_snapshot.vspec"


I would get rid of _snapshot

sschleemilch · 2026-05-20T08:59:30Z

+QUANTITIES_SNAPSHOT_FILENAME = "quantities_snapshot.yaml"
+
+
+def _filter_raw_node(attrs: dict[str, Any], exclude_fields: list[str]) -> dict[str, Any]:


maybe reuse https://github.com/COVESA/vss-tools/blob/master/src/vss_tools/model.py#L87?

sschleemilch · 2026-05-20T09:16:18Z

+
+
+def load_flat_yaml(path: Path) -> dict[str, Any]:
+    """Load a flat snapshot YAML file. Returns empty dict when file is absent."""


what means flat?

sschleemilch · 2026-05-20T09:23:15Z

+    out_text = json.dumps(result, indent=2, ensure_ascii=False)
+
+    if output:
+        output.write_text(out_text, encoding="utf-8")


shouldn't we do a json.dump here?

erikbosch · 2026-05-26T14:09:14Z

MoM:

Daniel checking comments

erikbosch · 2026-06-02T14:12:18Z

+
+## What it does
+
+A vspec model is typically spread across many files: a main `.vspec`, optional `#include` files, overlays, a units file, and a quantities file. `vspec compose` collapses all of that into a single **self-contained folder** (a _snapshot_) that any downstream `vspec export` command can consume without needing the original source tree.


Maybe worth stating the differences compared to the "vspec export yaml" command, because they have some similarities, right? Like long term, do we need both?

erikbosch · 2026-06-02T14:34:14Z

MoM:

Shall not be merged until model ledger merged and package created
Feel free to test out

erikbosch · 2026-06-16T14:07:58Z

MoM:

@jdacoello - what is the status of the model ledger package (https://github.com/COVESA/model-ledger)

erikbosch · 2026-06-23T13:47:32Z

COnflicts

erikbosch · 2026-07-06T08:33:33Z

Any updates on the status of this one @jdacoello

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

…itities Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

…irst-run mode support Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

… logic Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

erikbosch · 2026-07-28T12:44:03Z

What is the current status @jdacoello

erikbosch · 2026-07-28T14:34:37Z

MoM:

JD: Ledger dependency missing
JD: Will set up call with @erikbosch , will add ledger package to pypi
E: Friday or Monday afternoon works

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

jdacoello mentioned this pull request May 13, 2026

feat(registry): implement stable identifier registry #509

Closed

erikbosch reviewed May 18, 2026

View reviewed changes

Comment thread docs/compose.md

sschleemilch reviewed May 20, 2026

View reviewed changes

erikbosch reviewed Jun 2, 2026

View reviewed changes

erikbosch mentioned this pull request Jun 3, 2026

Anyone using "vspec export id"? #533

Open

jdacoello added 11 commits July 23, 2026 13:36

feat(compose): implement vspec composition command with output snapshots

32b3b6e

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

feat: Add units and quantities to the output of compose

b4f1df3

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

fix: Handle case when properties of expected intances as given

0f8565e

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

feat: Add diff command to compare two composed snapshots

cd6b2a1

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

docs: Add documentation for compose and diff commmands

3b4b53b

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

fix(compose): Move it out of the exporters directory

50cc075

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

fix(compose): Add a note about fallback behaviour for units and quant…

1dedb88

…itities Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

docs: Update references with 3 top level CLI commands

7b94ff3

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

feat(diff): Enhance diff functionality with modl IR translation and f…

08cd616

…irst-run mode support Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

feat: Add ModL ledger as depencency (not pip package yet)

2099b8a

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

feat(diff): Add instance expansion handling for ENTITY events in diff…

b77d9fe

… logic Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

jdacoello force-pushed the feat/diff branch from eb9442e to b77d9fe Compare July 23, 2026 15:04

erikbosch mentioned this pull request Jul 31, 2026

Follow up to #521 #547

Open

fix: Add modl pypi instead of commit

4423895

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

		QUANTITIES_SNAPSHOT_FILENAME = "quantities_snapshot.yaml"


		def _filter_raw_node(attrs: dict[str, Any], exclude_fields: list[str]) -> dict[str, Any]:



		def load_flat_yaml(path: Path) -> dict[str, Any]:
		"""Load a flat snapshot YAML file. Returns empty dict when file is absent."""


		## What it does

		A vspec model is typically spread across many files: a main `.vspec`, optional `#include` files, overlays, a units file, and a quantities file. `vspec compose` collapses all of that into a single self-contained folder (a _snapshot_) that any downstream `vspec export` command can consume without needing the original source tree.

Uh oh!

Conversation

jdacoello commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

erikbosch commented May 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erikbosch commented May 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erikbosch commented Jun 2, 2026

Uh oh!

erikbosch commented Jun 16, 2026

Uh oh!

erikbosch commented Jun 23, 2026

Uh oh!

erikbosch commented Jul 6, 2026

Uh oh!

erikbosch commented Jul 28, 2026

Uh oh!

erikbosch commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants