eclipse-score / eclipse-score/tooling

component_sequence naming-consistency check ignores 'actor' participant type, contradicting own docs example

Open
#338 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
8
Forks
37
Avg merge
2d 13h
Merged PRs (30d)
22

Description

## Summary

`component_sequence_validator`'s naming-consistency check (`check_participant_aliases`) enforces exact SET equality between `<>` aliases in component diagrams and *all* participant aliases used in sequence diagrams. This appears to discard the PlantUML `actor` participant type, even though the parser tracks it, and even the tool's own documentation example looks like it would fail this check.

## Observed behavior

In `validation/core/src/models/sequence_diagram_models.rs`, `SequenceDiagramIndex::from_diagrams` builds `used_participants` purely from `interaction.caller`/`interaction.callee` (and `ret.caller`/`ret.callee`), with no distinction based on participant kind (`participant` vs `actor` vs `boundary`, etc.):

```rust
if !interaction.caller.is_empty() {
used_participants.insert(interaction.caller.clone());
}
if !interaction.callee.is_empty() {
used_participants.insert(interaction.callee.clone());
}
```

`component_sequence_validator.rs::check_participant_aliases` then requires this set to equal exactly the set of `<>` aliases from the component diagrams (bidirectional check: "Missing sequence participant" and "Unexpected sequence participant").

Meanwhile, the PlantUML sequence-diagram parser (`plantuml/parser/puml_parser/src/sequence_diagram/src/syntax_parser.rs`) *does* parse `actor` as a distinct `ParticipantType::Actor` (`"actor" => Some(ParticipantType::Actor)`), and the component-diagram parser has an equivalent `ComponentType::Actor`. This information appears to be dropped before it reaches the FlatBuffers model consumed by `SequenceDiagramIndex`.

## Expected behavior

`architectural_design.md` itself documents the following canonical dynamic-view example:

```
@startuml MySeooc_WriteSequence

actor Caller
participant KeyValueStore
participant StorageBackend

Caller -> KeyValueStore : write(key, value)
KeyValueStore -> StorageBackend : flush()
StorageBackend --> KeyValueStore : OK
KeyValueStore --> Caller : Result::Ok

@enduml
```

Here `Caller` is declared with the `actor` keyword and is *not* a `<>` in the paired static diagram (only `KeyValueStore` and `StorageBackend` are). Based on the validator code, `Caller` would be collected into `used_participants` (it appears as caller/callee of two interactions) and then fail "sequence participant not found in component unit aliases," since no `<>` alias named `Caller` exists.

Expected: `actor`-typed sequence participants represent entities outside the validated architectural boundary (external callers, consumers, generated/out-of-tree code, etc.) and should be excluded from the naming-consistency SET-equality check — consistent with standard UML "actor" semantics and with the tool's own documented example.

## Why this looks like a tooling bug, not a deliberate design choice

- The parser already distinguishes `actor` from `participant`/`boundary`/etc. at the syntax level for both sequence and component diagrams.
- The static-side validator (`bazel_component_validator`) *does* filter by stereotype (`<>`/`<>`/`<>`), ignoring plain/unstereotyped elements — the dynamic-side validator has no equivalent filter, seemingly because participant-kind information is lost between parsing and the FlatBuffers model consumed here.
- The docs' own reference example (`architectural_design.md`, Dynamic Architecture section) would not pass validation as written, based on this code path.

## Impact

There's currently no supported way to document an interaction with an out-of-boundary actor (e.g. an external caller, or code generated outside the dependable element's own Bazel package) in a sequence diagram without either:
- inventing a fictional Bazel `unit()` purely to satisfy the validator, or
- omitting the actor from the sequence entirely and only referencing it in prose/notes.

## Suggested fix

Preserve `ParticipantType`/`ComponentType` (or at least an `is_actor` flag) through to the FlatBuffers model, and exclude `actor`-typed participants from the naming-consistency and interface-consistency checks in `component_sequence_validator.rs`. This would align enforced behavior with the tool's own documented example and with standard UML actor semantics.

## Suspected area

- `plantuml/parser/puml_parser/src/sequence_diagram/` (parser retains `ParticipantType::Actor`, downstream FlatBuffers model may not)
- `validation/core/src/models/sequence_diagram_models.rs` (`used_participants` collection, no kind filter)
- `validation/core/src/validators/component_sequence_validator.rs` (`check_participant_aliases`)
- `bazel/rules/rules_score/docs/user_guide/architectural_design.md` (documented example that appears inconsistent with current validator behavior)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by tracing ParticipantType::Actor from plantuml/parser/puml_parser/src/sequence_diagram/ through validation/core/src/models/sequence_diagram_models.rs and into component_sequence_validator.rs. Compare the documented actor example in bazel/rules/rules_score/docs/user_guide/architectural_design.md with the naming and interface checks. Done means actor participants remain distinguishable and are excluded from the relevant consistency checks without weakening checks for validated participants.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.