feat(view): render GeneralView requirement, definition, package and use case graphs

[devin-ai-integration]

Depends on #871. This branch merges feature/view-case-mixed and draws the case diagram with its case kind and writers; merge #871 first.

What and why

A GeneralView is drawn as a containment tree only, while StandardViewDefinitions describes its typical rendering as a graph of nodes and edges, specialised by the view's element filters. This renders three of those specialisations as graphs:

• requirement (KindRequirement): requirement and concern definitions/usages as nodes, with short name/ID and a text excerpt; edges for satisfy, verify, derive, refine, allocate, specialization and typing.
• definition (KindDefinition): definitions and usages with specialization, typing, and composition/reference edges (a usage feature drawn to its type, filled or hollow diamond by compositeness).
• package (KindPackage): packages, package containment and package imports.

All three are written by the text, Mermaid, DOT, PlantUML and D2 writers, with the existing palettes and the Pilot/Cameo drawing styles (Cameo frames req, bdd, pkg). In D2 the relationships take the class-diagram notation as classes (specialization, dashed typing, composition/reference diamonds and a containment circle at the owner, a dashed dependency for import, satisfy, verify, derive, refine and allocate). A case or mixed rendering has no D2 form, as on develop; asking for one is refused with the usual wrong-form error.

Which filters select which graph

A GeneralView is drawn as a graph only when every filter member (and every filtered expose) compiles to a direct @Metaclass / @@Metaclass test on a SysML/KerML metaclass, or an or of such tests. The metaclass and its library supertypes decide the graph: RequirementDefinition/RequirementUsage (and concern) select a requirement graph, Package a package graph, Definition/Usage a definition graph; relationship metaclasses (Specialization, FeatureTyping, SatisfyRequirementUsage, …) select none on their own. CaseDefinition/CaseUsage select a case diagram (below). When several are named, requirement wins over package, package over case, and case over definition. An unfiltered GeneralView, and any filter outside these shapes (conjunctions, negations, metadata or feature tests, an or with such an operand), keeps the containment tree byte for byte. The mapping is documented in docs/project/view-rendering-forms.md#generalview-graphs.

Use case diagrams through a GeneralView

A GeneralView whose filter names CaseDefinition, CaseUsage or a specialization — UseCaseDefinition, UseCaseUsage, the analysis and verification cases — returns KindCase and is drawn by #871's case writers, with no second writer, using only the standard library:

view useCaseView : StandardViewDefinitions::GeneralView {
    filter @SysML::UseCaseUsage;
    expose VehicleUseCases::'Provide Transportation';
}

CaseView (OpenSysMLRenderings) is the shorter way to write the same view; mixed diagrams still need MixedView. general_case_test.go renders a filtered GeneralView and a CaseView exposing the same elements and compares their text, Mermaid, DOT and PlantUML output with source links. Every byte matches except the provenance line, which names how each view got its kind: view def GeneralView, filter @UseCaseUsage for the GeneralView, render asCaseDiagram for the CaseView. The test checks that this line is the only difference. The route works on the CLI, REPL, LSP and in documents; a verdicts overlay on it is refused like on any non-requirement kind. Example: examples/general-views-demo/use-cases.sysml.

docs/project/view-rendering-forms.md also gains a "Standard views first" section: each rendering's route, marked standard (GeneralView filters, GridView matrix) or extension (MixedView, the DocumentQueries verdicts overlay, layout), with run renderings CLI/REPL only.

Verdict overlay (opt-in)

Without an overlay a requirement graph is purely structural and deterministic. With the verdicts overlay, the verification cases verifying each drawn requirement are run and the requirement is labelled and coloured by its worst verdict (pass < inconclusive < fail < error, Okabe–Ito colours); each case and its detail are listed in the node detail. Surfaces:

• CLI -render-overlay verdicts (with -render/-render-all)
• REPL %render <view> [form …] verdicts
• LSP opensysml/render parameter overlay, advertised as openSysmlRenderOverlays; node data carries verdict
• document Diagram::overlay (optional attribute in OpenSysML Libraries/DocumentQueries.sysml; no new library)

An overlay on any other kind is refused. The verdicts run in a typed runtime: the REPL's session runtime, an LSP runtime built through modelrt from a detached reading (so internal/workspace/model still does not import the runtime), and in documents the query context's runtime or its typed declared reader (queryexec.Context.Verifier). The view package does not import the runtime; runtime.RequirementVerdicts adapts verdicts to view.Verdicts.

Source links

The graphs carry the source links of -render-link, REPL link=<template> and LSP linkTemplate the way every other kind does: each requirement, definition, usage and package node, and each relationship edge with a declaration, links to it in Mermaid (click), DOT (URL/tooltip) and PlantUML ([[…]]). A link template combines with the verdicts overlay; in the LSP both are drawn from one read of the workspace (Reading.LinkSites). Linked goldens: internal/ir/view/testdata/links-general-*.golden.

The requirements table was not added: the existing table kind and the in-flight GridView relationship matrix cover it.

Specification basis

SysML v2 StandardViewDefinitions::GeneralView (Systems Library) — its documented package, definition-and-usage and requirement specialisations by element filter. Adds a row to docs/project/spec-compliance.md.

How it was verified

• Goldens for each specialisation in each form (internal/ir/view/testdata/general*.golden), Pilot and Cameo styles; verdict overlay goldens from a deterministic verification run.
• Byte-identity: unfiltered and unrecognised-filter GeneralViews are compared against the tree rendering; no existing golden changed.
• Robustness: cyclic part definitions, recognised filter with an empty result, unresolved relationship ends (notices, no panic), filtered expose.
• CLI, REPL, LSP and docplan tests for the overlay, including refusal on non-requirement kinds and unknown overlays.
• examples/general-views-demo/vehicle.sysml and the two view fixtures validate with the pinned pilot validator with 0 errors.
• examples/general-views-demo/use-cases.sysml and internal/ir/view/testdata/general-case.sysml validate with 0 errors with only the pilot's standard library (no OpenSysML Libraries folder).
• Case route: classifier cases for every case-family metaclass and the mixed-filter precedence, goldens per form, linked goldens, and CLI/REPL/LSP/docplan tests.
• D2 goldens for the three graphs, the verdict overlay and the linked graphs, each compiled by d2 0.9.0 (OPENSYSML_D2), and TestD2GeneralGraphNotation for the edge notation.
• go build ./..., go vet ./..., gofmt -l ., make docs-check, make docs-counts, make man-check, make stdlib-snapshot-check.

Regenerated artifacts, all from the added example or library attribute: the pilot differential baseline and the counts derived from it (384 files, 346 fully agreeing), the RDF/API-JSON corpus round-trip expectations (two new stable files), the embedded stdlib snapshot, the self-model ViewEngine kinds (13 recognised, 11 supported, with #871's two), and the man page.

Renderings of the example

Requirement graph with verdicts (DOT, Okabe–Ito):

Requirement graph (Mermaid):

Definition/usage graph (DOT, Cameo style):

Definition/usage graph (DOT):

Definition/usage graph (Mermaid; a flowchart has no diamond head, so composition and reference lead their label with ◆ and ◇):

Requirement graph (PlantUML):

Package graph (PlantUML):

Use case diagram through GeneralView + filter @SysML::UseCaseUsage; (Mermaid, DOT, PlantUML):

D2 (definition and package graphs, requirement graph with verdicts and source links), compiled with d2 0.9.0:

Definition graph	Package graph

Checklist

• make test and make lint pass locally — go test ./... passes locally; make lint was not run locally, CI runs it
• 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

[devin-ai-integration]

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

[devin-ai-integration]

End-to-end check through the sysml CLI and REPL at b2bb8b1: passed.

• The three views of examples/general-views-demo rendered in all four forms × Pilot/Cameo, and every DOT/Mermaid/PlantUML output was converted to PNG.
• -render-overlay verdicts: vehicleMass fail, emergencyStop inconclusive, a pass case, and pass/error aggregation on a further fixture. Refused on a definition view, for an unknown overlay, and without -render.
• REPL: %render … verdicts, verd → verdicts completion, and the refusal notice on a definition view.
• Unfiltered views and views with and, not, metadata or mixed filters: 24 outputs byte-identical to develop.
• Cyclic definitions, a recognised filter with an empty result, and dangling relationship ends (REPL): finite output with notices, no panic.

The first run found two rendering issues, fixed in b2bb8b1: PlantUML showed boxed U+0022 glyphs at requirement excerpt quotes, and Mermaid composition and reference edges were indistinguishable.

PlantUML excerpts	Mermaid ◆ composition / ◇ reference

Requirement verdict overlay (DOT)	Definition graph (DOT, Cameo)

The LSP was covered only by its unit and integration tests.

[devin-ai-integration]

End-to-end testing of the GeneralView case route passed on d1bdea6, through the CLI, the REPL, real Mermaid/Graphviz/PlantUML conversion and the pilot validator. The later 71c6c7a change only moves a comment.

GeneralView case diagrams

Both demo views render as case diagrams in all four forms. The usage diagram shows the subject, actors, objective and both includes. The definition diagram shows 'Add Fuel' and 'Enter Vehicle'.

Mermaid	PlantUML

Equivalence, regression and refusal checks

• With source links, the GeneralView and an explicit CaseView give the same Mermaid, DOT and PlantUML output except the provenance line (view def GeneralView, filter @UseCaseUsage vs render asCaseDiagram).
• All eight case-family filters selected case. Nested-case composition worked, relationship metaclasses beside a case filter worked, and the precedence checks passed (requirement > package > case > definition).
• Unfiltered, conjunction and negation filters still draw trees. The vehicle requirement, definition and package outputs matched the committed goldens.
• verdicts overlays on the case route are refused with a clear error in the CLI (exit 2) and the REPL.
• The pilot validator, given only the standard library, accepts use-cases.sysml with exit 0 and no diagnostics.

Recording of the session: https://nasa-jpl-demo.devinenterprise.com/sessions/f27da938b63c4728b79cc2ce04d15c17

Written by Devin

[devin-ai-integration]

This branch now conflicts with develop. Conflicting files, and the merged PRs that changed them:

• docs/project/pilot-differential-baseline.json (fix(runtime): explore every order of unordered statements in calc, constraint and case bodies #864)

To resolve: merge current develop into this branch with an ordinary merge commit (no rebase or force-push).
Don't hand-merge generated files: regenerate docs/project/pilot-differential-baseline.json with go run -C tools ./cmd/pilot-diff -update after the merge.

Planned merge order for the view and docs PRs: #889 → #881 → #871 → #882 → #884 → #885 → #886. Each needs these files regenerated again after the one before it merges.

Re-run the full gate (go build ./..., go vet ./..., gofmt -l ., make lint, make docs-check, go test ./...) and wait for green CI before marking ready.

[devin-ai-integration]

Hold on pushes: please don't push to this branch, including develop merges or empty commits to retrigger CI, until a maintainer says the CI runners are free. Prepare the conflict resolution locally and push it then.