Skip to content

feat(view): add source links to rendered diagrams - #867

Merged
HuiJun merged 5 commits into
developfrom
feature/render-source-links
Oct 4, 2026
Merged

HuiJun merged 5 commits into
developfrom
feature/render-source-links

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Rendered diagrams can now link every node and edge back to its declaration. A link template with {file}, {line}, {col}, {qname} and {id} is set on view.Options.Links and written by every graph form:

  • DOT: URL= and tooltip= (qualified name, else file:line:col) on nodes and edges. A composite node puts them on its cluster, so the SVG links the visible box.
  • PlantUML: [[url]] on node declarations (after stereotypes, before palette colours) and on edges. Ports, pseudostates (<<start>>, <<fork>>, <<join>>, <<end>>, <<choice>>, <<history>>, <<history*>>) and initial arrows stay unlinked, because the pinned jar drops those links from the SVG. Inside a linked composite state, the jar gives an unlinked pseudostate the composite's link.
  • Mermaid: click <id> href "<url>" on flowchart nodes and simple states, link <id>: Source @ <url> on sequence participants. Edges, subgraphs and composite states have no Mermaid link syntax. Mermaid drops the URL fragment (#L26) from sequence participant links in SVG.

Surfaces: CLI -render-link '<template>' (with -render, -render-all and document rendering), REPL %render … link=<template>, LSP opensysml/render linkTemplate, document backends (Markdown/HTML/PDF diagrams), and the VS Code export, which sends <uriScheme>://file/{file}:{line}:{col}.

Decisions:

  • {file} is the source path as loaded (slash-normalised), not rewritten against a root; absolute input paths are recommended for vscode:///file:// templates.
  • {id} is the element's effective id from identity.Of (declared elementId or the derived one, per element-identity-annotations.md).
  • Zero/synthetic origins, bundled library declarations and non-file documents are not linked.
  • Substituted values percent-encode everything but unreserved characters, / and :; template literals keep URL delimiters (#, ?, &, %) and escape grammar-unsafe bytes (space, ", ], braces, non-ASCII).
  • No template means no change: every existing golden is untouched and a test asserts byte identity.
  • The HTML document backend has no per-element sections today, so diagram nodes use the template rather than a same-document anchor.
  • The LSP freezes source sites under the workspace lock, and only when a template is given.
  • Mermaid's securityLevel is left at its default (strict). Measured with the pinned mermaid-cli 11.16.0: strict mode strips non-HTTP(S) schemes (vscode://, file:///), and loose keeps them. This is documented, not changed.

Specification basis

Diagram rendering is tool-defined (SysML v2 §8.2.2.2). The "hyperlinks are not written" limitation is removed from docs/project/view-rendering-forms.md, and a source-links row is added to the rendering table in docs/project/spec-compliance.md.

How it was verified

  • go build ./..., go vet ./..., make lint, go test ./..., plus go test -race on internal/frontend/lsp and internal/workspace/model; make man-check, make docs-counts.
  • internal/ir/view/links_test.go: linked goldens for DOT, PlantUML and Mermaid (tree, interconnection, state, action, sequence), escaping (spaces, ], quotes, #, non-ASCII), zero origins, anonymous elements, invalid templates, no-template byte identity. Surface tests for CLI, REPL, LSP, workspace and document rendering.
  • SVG survival, all three checked: Graphviz dot -Tsvg writes <a xlink:href>/xlink:title; the pinned PlantUML jar (1.2026.8, -tsvg) writes node and edge <a>, and every link the writer emits has its own href in the SVG; mermaid-cli 11.16.0 writes <a> for flowchart, state and sequence links (HTTP(S) only under strict mode). The tests run all three when the tools are present.
  • End-to-end runs: the CLI across 17 view/form combinations and -render-all, the REPL, and the HTML backend, where clicking a linked state opens its source at #L59. In VS Code, a diagram-panel export gave an SVG whose link opened the file at Ln 43, Col 9. A path with spaces, ] and é opened from the Graphviz SVG. With no template, all 17 outputs were byte-identical to develop.

Graphviz SVG in Chrome, hovering tank : Tank (tooltip shows the qualified name, the status bar shows the source URL), and VS Code opened from the exported SVG's link:

Hovered source link in a Graphviz SVG

VS Code opened at the linked declaration

Checklist

  • make test and make lint pass locally
  • Tests added or updated for the change
  • Documentation extended where it already covers the surface (see CONTRIBUTING.md)
  • Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
  • baselines regenerated and make docs-counts run if a gate count moved (compliance rows need nothing: the census is counted at docs build)
  • No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/c9d4fd36122441dabea9dd6883c66b06
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/c9d4fd36122441dabea9dd6883c66b06?variant=devin
Requested by: @HuiJun

devin-ai-integration Bot and others added 3 commits October 3, 2026 21:30
Co-Authored-By: jason.han <hanhuijun@gmail.com>
Co-Authored-By: jason.han <hanhuijun@gmail.com>
Co-Authored-By: jason.han <hanhuijun@gmail.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

Co-Authored-By: jason.han <hanhuijun@gmail.com>
@devin-ai-integration
devin-ai-integration Bot marked this pull request as ready for review October 3, 2026 23:36
devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: jason.han <hanhuijun@gmail.com>
@HuiJun
HuiJun merged commit b2763ff into develop Oct 4, 2026
24 checks passed
@HuiJun
HuiJun deleted the feature/render-source-links branch October 4, 2026 05:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant