refactor(plantuml): introduce Rust idmap generation and CLI source-aware output wiring by AAmbuj · Pull Request #321 · eclipse-score/tooling

AAmbuj · 2026-07-07T09:45:42Z

This change introduces a Rust-native idmap generation flow in the PlantUML parser pipeline and wires the CLI to emit source-aware idmap outputs.

What is included:

Added a new Rust idmap library to generate idmap sidecar data for supported diagram models.
Extended the CLI with source-aware output handling for idmap emission.
Updated related Rust integration points so idmap output can be produced consistently during parsing.

Why:

Establishes deterministic, source-anchored link metadata at parse time.
Simplifies downstream consumption by producing structured sidecar data directly from Rust components.
Enables incremental adoption of idmap-based linking with a focused, testable Rust-only scope.

melodyoncode · 2026-07-08T08:36:34Z

+    /// Stable workspace-relative source name baked into generated artifacts
+    /// (FlatBuffers/lobster/idmap ``source`` field). When omitted, the
+    /// filesystem basename is used as a fallback.
+    #[arg(long)]
+    source_name: Option<String>,


--source-name doesn't scale to multiple input files because a single CLI argument cannot be mapped unambiguously to multiple sources. The source field is a property of each input file and should be derived from the file path itself (preferably converted to a workspace-relative path), rather than being supplied independently by the caller.

https://github.com/eclipse-score/tooling/pull/321/changes#diff-ef61e73864f06341474fbdb1d6ddf32e8bc976be5debfed7948908304a447208R235

https://github.com/eclipse-score/tooling/pull/321/changes#diff-ef61e73864f06341474fbdb1d6ddf32e8bc976be5debfed7948908304a447208R624

Addressed. I removed the CLI-level source override and now derive source per input file path, using workspace-relative paths when possible.

melodyoncode · 2026-07-08T08:45:10Z

                        ResolvedDiagram::Sequence(_) => LobsterModel::Empty,
                    };
-                    write_lobster_to_file(lobster_model, path, ldir)?;
+                    write_lobster_to_file(lobster_model, path, Some(source_file), ldir)?;


path and source_file are effectively the same thing. I don't think we need to change fucntion write_lobster_to_file signature here.

https://github.com/eclipse-score/tooling/pull/321/changes#diff-ef61e73864f06341474fbdb1d6ddf32e8bc976be5debfed7948908304a447208R247

https://github.com/eclipse-score/tooling/pull/321/changes#diff-a0383766e0852cdd7252290c4045bd1144fcd7150300d7efc3309ecef242a3a5L134

Addressed. I simplified the lobster writer API to take a direct source path string (not an optional override), and updated call sites accordingly.

melodyoncode · 2026-07-08T09:30:17Z

+    /// `true` when this diagram elaborates the element (i.e. it is listed
+    /// under `defines`).  Omitted from the JSON for plain references.
+    #[serde(default, skip_serializing_if = "is_not_elaborated")]
+    pub elaborated: bool,


Is elaborated still needed here? The split between defines and references already conveys the same information. Unless there are cases where a define can be non-elaborated (or a reference elaborated), this field seems redundant.

I removed elaborated from idmap entries. Define/reference role is now represented only by membership in defines vs references arrays.

melodyoncode · 2026-07-08T09:34:20Z

+/// `parent_id` (i.e. it has children and is therefore elaborated here).
+/// All remaining elements are **references** (top-level leaves that mention
+/// something that may be detailed in another diagram).
+fn comp_model_to_idmap(


One question: how should packages be handled in this case?

For example:

package P { component A { component AA } }

Since both package P and component A have children, the current rule "elements with children" seems to classify both as defines. Is that the intended behavior, or should packages be treated purely as containers/namespaces rather than emitted as definitions?

https://github.com/eclipse-score/tooling/pull/321/changes#diff-709f3e26145f0c12fb692763aa84eb4bfc303f710743183598aac1278584fd2dR99

https://github.com/eclipse-score/tooling/pull/321/changes#diff-709f3e26145f0c12fb692763aa84eb4bfc303f710743183598aac1278584fd2dR628

Packages are now treated as containers/namespaces and are not emitted as idmap define/reference entrie

melodyoncode · 2026-07-08T09:45:15Z

+        let has_members = !entity.methods.is_empty() || !entity.variables.is_empty();
+        let matches_diagram_name = diagram_name == Some(entity.name.as_str());
+        let is_define = has_members || matches_diagram_name;
+        let entry = IdMapEntry {


I don't see any handling of entity.relationships here. Since the proposal defines references to include relation endpoints, shouldn't those be emitted as reference entries as well?

I now add relationship source/target endpoints as references (deduplicated, and not duplicating defines).

melodyoncode · 2026-07-08T09:57:20Z

+}
+
+/// Collect the unique participant names from a sequence tree.
+fn collect_participants(tree: &SequenceTree) -> HashSet<String> {


This currently derives participants from interaction endpoints (caller/callee). We have a planned follow-up to persist participant declarations in the AST, so this logic should be updated to use the explicit participant list instead of reconstructing it here.

Partially addressed for now. The current SequenceTree model does not yet persist explicit participant declarations, so behavior remains endpoint-derived. I added a TODO marker to switch to declaration-based sourcing once the resolver/AST exposes participants explicitly.

melodyoncode · 2026-07-08T10:01:48Z

+    Class(&'a ClassDiagram),
+    Sequence(&'a SequenceTree),
+    Fta(&'a FtaModel),
+    Empty,


Do we really need the Empty variant here? It seems to conflate several different states (no model, unsupported diagram type, empty diagram, parse failure, etc.).

I removed Empty from IdMapModel and introduced an explicit empty writer API used only where intentionally empty output is desired (for example activity diagrams).

Emits a per-source .idmap.json with defines[] / references[] entries used by the clickable_plantuml Sphinx extension to resolve cross-diagram links. Supports Component, Class, Sequence, Activity (empty), and FTA diagrams.

Calls write_idmap_to_file() for every resolved diagram. Passes short_path as source_name so both idmap and lobster outputs use the stable workspace-relative path rather than the sandbox-local filesystem path.

AAmbuj marked this pull request as ready for review July 7, 2026 09:57

AAmbuj requested review from LittleHuba, castler, hoe-jo, limdor and ramceb as code owners July 7, 2026 09:57

melodyoncode suggested changes Jul 8, 2026

View reviewed changes

feat(puml_idmap): add idmap Rust library for all diagram types

ccb0f24

Emits a per-source .idmap.json with defines[] / references[] entries used by the clickable_plantuml Sphinx extension to resolve cross-diagram links. Supports Component, Class, Sequence, Activity (empty), and FTA diagrams.

AAmbuj force-pushed the amsh_refactor_plantuml_rust_idmap_cli branch from f551a99 to eb2921f Compare July 9, 2026 07:21

feat(puml_cli): wire --idmap-output-dir and --source-name into CLI

b4dcb24

Calls write_idmap_to_file() for every resolved diagram. Passes short_path as source_name so both idmap and lobster outputs use the stable workspace-relative path rather than the sandbox-local filesystem path.

AAmbuj force-pushed the amsh_refactor_plantuml_rust_idmap_cli branch from eb2921f to b4dcb24 Compare July 9, 2026 07:53

AAmbuj requested a review from melodyoncode July 9, 2026 08:58

Uh oh!

Conversation

AAmbuj commented Jul 7, 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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants