Skip to content

Enhance AST and rendering for annotations, enums, and requirements#32

Merged
Malcolmnixon merged 7 commits into
mainfrom
feature/annotating-elements-compartment-depth
Jul 13, 2026
Merged

Enhance AST and rendering for annotations, enums, and requirements#32
Malcolmnixon merged 7 commits into
mainfrom
feature/annotating-elements-compartment-depth

Conversation

@Malcolmnixon

Copy link
Copy Markdown
Member

This pull request delivers the "Annotating elements & compartment depth" feature for the SysML2 tools, improving both the semantic model and the General View layout to support documentation notes, enumeration literal values, and deeper compartment rendering for requirements, concerns, and constraints. It also updates the documentation and gallery model to demonstrate these capabilities. The most important changes are grouped below:

Semantic Model & AST Builder Enhancements:

  • The AstBuilder now captures all relevant content for compartment depth: enumeration values (with a new VisitEnumeratedValue and CollectEnumerationBodyChildren), requirement/concern subject, actor, stakeholder, and constraint members (with new visitors and helpers), and standalone constraint usages/definitions. It also adds a safeguard to prevent nested verify/frame bodies from being incorrectly hoisted. [1] [2] [3] [4]
  • The SysmlFeatureNode type gains an ExpressionText field to capture raw constraint expressions, which is used for rendering constraint-kind features.

General View Layout & Rendering:

  • GeneralViewLayoutStrategy is updated to thread through definition annotations, enabling the rendering of BoxShape.Note nodes (folded-corner notes) attached to annotated elements, with concatenated annotation text. The layout also pluralizes certain compartment titles using guillemets for stereotype-style headings and renders constraint expressions as raw text. [1] [2] [3] [4]

Documentation & Gallery Model Updates:

  • The gallery model (01-drone-general.sysml) is extended with annotated elements, an enum def with values, and a requirement with subject and constraint body to demonstrate the new features. The gallery README is updated to describe these additions.
  • Design documentation is updated to describe the new AST builder behaviors, feature node shape, and layout strategy logic. [1] [2] [3] [4] [5] [6] [7] [8]

Scope and Limitations:

  • This delivery captures only raw constraint text (not full expression trees) and intentionally does not model nested doc annotations within constraint bodies or support views other than General View. [1] [2]

Summary of Most Important Changes:

  • Semantic model and AST builder now fully support documentation notes, enumeration values, and deep compartment content for requirements/concerns/constraints, including new visitors and helpers. [1] [2] [3] [4]
  • SysmlFeatureNode gains ExpressionText for constraint-kind features, enabling raw expression rendering.
  • General View layout strategy renders annotation notes, stereotype-titled compartments, and constraint expressions as raw text, with updated compartment grouping and formatting logic. [1] [2] [3] [4]
  • Documentation and gallery model are updated to demonstrate and explain the new features and rendering behaviors. (Fc08c939cL44R44)
  • Scope boundaries are documented: only raw text is captured for constraints, and nested doc inside constraint bodies is intentionally omitted. [1] [2]

Malcolm Nixon added 7 commits July 12, 2026 19:03
…r gaps

Comment/doc annotation text is already captured semantically but never
read by GeneralViewLayoutStrategy; enum literal values, constraint
bodies, and requirement subject/constraints/doc are not captured in
the AST at all yet. Cites the spec's stereotype-style compartment
title conventions (subject, doc, constraint).
…e constraints in AstBuilder

- Add nullable ExpressionText to SysmlFeatureNode, mirroring SysmlTransitionNode.Guard,
  for constraint-kind features' raw expression text.
- VisitEnumerationDefinition: full body-collecting visitor via new
  CollectEnumerationBodyChildren helper, since enumerationBody uniquely alternates
  annotatingMember/enumerationUsageMember directly rather than wrapping them in a single
  rule. VisitEnumeratedValue builds an 'enum value'-keyword feature for each literal
  (bare, value-assignment, and redefinition-body forms).
- VisitRequirementDefinition/VisitConcernDefinition: full body-collecting visitor
  (push-scope/CollectChildren(requirementBodyItem)/register), mirroring VisitStateUsage's
  established pattern. Also extend VisitRequirementUsage/VisitConcernUsage the same way,
  beyond a literal *Definition-only reading of the plan, because the dominant real OMG
  corpus idiom nests subject/assume constraint inside a requirement usage that
  specializes a def, not inside the def's own body.
- New VisitSubjectUsage/VisitActorUsage/VisitStakeholderUsage (subject/actor/stakeholder
  keywords) and VisitRequirementConstraintMember/BuildConstraintFeatureNode (require
  constraint/assume constraint keywords, capturing raw expression text for both the
  reference and inline requirementConstraintUsage grammar alternatives).
- New VisitConstraintUsage (previously entirely absent) and rewritten
  VisitConstraintDefinition, synthesizing a 'constraint'-keyword child feature carrying
  the raw calculationBody text.
- New VisitRequirementVerificationMember/VisitFramedConcernMember returning null: once
  body-collection reaches requirementBodyItem, ANTLR's default dispatch would otherwise
  recurse into a nested verify/frame member's own body and incorrectly hoist its content
  onto the outer enclosing requirement.
- Add DefBox.Annotations, threaded through CollectDefinitions.
- New AddAnnotationNote/BuildNoteText/ComputeNoteBoxSize helpers: emit one
  BoxShape.Note box per annotated definition (concatenating multiple
  Documentation/Comment annotations into a single note), connected by a plain solid
  line with no end marker. Implemented as ordinary LayoutGraph nodes/edges added
  during the existing single-pass BuildGraph traversal, a documented deviation from
  a literal post-layout marker-decoration approach (this strategy has no equivalent
  decoration phase).
- Pluralize: add guillemet stereotype titles for subject/assume constraint/require
  constraint/constraint compartments, reusing the pre-existing «allocate» edge-label
  convention.
- FormatFeatureRow: render a constraint-kind feature's raw ExpressionText instead of
  the generic name : Type [multiplicity] row shape.
…t rendering

- WorkspaceLoaderTests: enum def bare/value-assignment literal capture, requirement
  def/usage subject+constraint capture, actor/stakeholder capture, standalone
  constraint usage/definition, and a verify-member no-hoist regression guard.
- OmgModelsTests: regression fixtures against the real OMG corpus for enumeration
  definitions, requirement definitions/usages, and comment/documentation examples.
- GeneralViewLayoutStrategyTests: note-box emission (including the no-note and
  multiple-annotations-combine-into-one cases), «subject» guillemet compartment
  title, constraint expression-text rows, and the enum values compartment title.
…ent changes

- ast-builder.md/general-view-layout-strategy.md design docs: describe the new
  visitor methods, the deliberate VisitRequirementUsage/VisitConcernUsage extension,
  the verify/frame null-suppression safeguard, and the AddAnnotationNote
  architectural deviation from a post-layout marker-decoration approach.
- sysml-node.md: document the new SysmlFeatureNode.ExpressionText field.
- Verification docs: add Test Scenarios entries for every new test.
- Reqstream YAMLs: add new requirement IDs with test traces, following the shape
  established by PR #30/#31.
…roadmap item delivered

- 01-drone-general.sysml: Battery gains a doc annotation, FlightMode is now an enum
  def with literal values, and FlightTimeRequirement gains a subject/require
  constraint body.
- Regenerate DroneGeneralView/BatterySubsystemView SVG and PNG.
- Update gallery README caption for the new content.
- ROADMAP.md: mark 'Annotating elements & compartment depth' delivered.
…ility gap in ast-builder requirement

The RequirementSubjectAndConstraints requirement in ast-builder.yaml claims coverage of both requirement and concern definition/usage paths (VisitConcernDefinition/VisitConcernUsage), but WorkspaceLoaderTests.cs only exercised requirement cases.

- Add WorkspaceLoader_LoadAsync_ConcernDefinitionAndUsage_CapturesSubject to WorkspaceLoaderTests.cs, verifying that a concern def and a concern usage each capture their subject member as a Children entry.
- Reference the new test in the RequirementSubjectAndConstraints requirement's tests list in docs/reqstream/sysml2-tools-language/semantic/model/ast-builder.yaml.
- Add the corresponding row to docs/verification/sysml2-tools-language/semantic/model/ast-builder.md.
@Malcolmnixon
Malcolmnixon merged commit af9be65 into main Jul 13, 2026
15 checks passed
@Malcolmnixon
Malcolmnixon deleted the feature/annotating-elements-compartment-depth branch July 13, 2026 01:03
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