DemaConsulting.SysML2Tools.Core 0.1.0-beta.5

SysML2 Tools

SysML2Tools is a free, open-source .NET CLI tool and library that parses SysML v2 textual model files and renders them as professional nested block diagrams suitable for architecture documentation, CI/CD pipelines, and AI-assisted modeling workflows.

Features

• SysML v2 Parsing: Parses SysML v2 textual notation (.sysml files) via an ANTLR4-generated parser against the official OMG grammar
• OMG Standard Library: Automatically loads and pre-resolves the OMG stdlib from embedded resources — no external installation required
• Multi-File Workspace: Accepts glob patterns to load multiple .sysml files as a single workspace; stdlib is always implicitly included
• Semantic Model: Full symbol table, reference resolution, import chain walking, and supertype chain resolution
• Structured Diagnostics: File, line, and column information on all errors and warnings
• lint Command: Load a workspace and report all diagnostics; exit non-zero if errors are present — suitable for CI/CD and AI-assisted model-fix loops
• render Command: Load a workspace, resolve a view, and render to SVG or PNG
• query Command: 11 model-analysis verbs (uses, used-by, impact, describe, hierarchy, requirements, interface, connections, states, list, find) for AI and human callers, with Markdown or JSON output — designed so an AI agent can query architecture and traceability facts directly instead of reading raw .sysml files
• help Command: Print help for the tool itself, a specific command (lint/render/query), or a specific query verb — identical output to the corresponding <command> --help
• GeneralView Layout: Package-grouped definition block diagrams placed by a layered (ELK-style) engine with orthogonal specialization and membership edges, depth-coded fill colors, compartments, and configurable depth limiting
• SVG Output: Zero external dependencies
• PNG Output: Pixel-identical across Windows, Linux, and macOS via SkiaSharp and an embedded Noto Sans font
• NuGet Library: Publishable packages with a stable public API — use the parser, semantic model, or layout engine independently of the CLI tool
• Self-Validation: Built-in validation tests with TRX/JUnit output for regulated environments
• Multi-Platform Support: Builds and runs on Windows, Linux, and macOS
• Multi-Runtime Support: Targets .NET 8, 9, and 10

Installation

Install the tool globally using the .NET CLI:

dotnet tool install -g DemaConsulting.SysML2Tools.Tool

Usage

Linting

Check a SysML v2 workspace for errors and warnings:

# Lint a single file
sysml2tools lint model.sysml

# Lint all .sysml files in a directory
sysml2tools lint "src/**/*.sysml"

Exit code is non-zero if any errors are present, making it suitable for CI/CD pipelines.

Rendering

Render a SysML v2 workspace to SVG or PNG. --output names an output directory (default: current directory); --format selects svg (default) or png:

# Render to SVG (auto-selects the single view in the workspace)
sysml2tools render model.sysml --output out --format svg

# Render to PNG
sysml2tools render model.sysml --output out --format png

# Render a named view from a multi-view workspace
sysml2tools render "src/**/*.sysml" --view SystemContext --output out --format svg

# Auto-render the top-level part def when no view is defined
sysml2tools render model.sysml --auto --output out --format svg

# Limit nesting depth (truncated parts show "+N more…")
sysml2tools render model.sysml --output out --depth 3

Querying

# What does this element depend on? (outgoing edges)
sysml2tools query uses --element Pkg::MyPart model.sysml

# What depends on this element? (incoming edges)
sysml2tools query used-by --element Pkg::MyPart model.sysml

# Fact sheet: kind, supertypes, typing, annotations, children
sysml2tools query describe --element Pkg::MyPart model.sysml

# List elements in the workspace, optionally filtered by kind and/or name
sysml2tools query list --kind part --name Engine "src/**/*.sysml"

# JSON output for scripting/automation
sysml2tools query uses --element Pkg::MyPart model.sysml --format json

See Querying in the user guide for the full verb reference and more examples.

Getting Help

# Top-level help (same as bare --help)
sysml2tools help

# Command-specific help (identical to `lint --help`/`render --help`)
sysml2tools help lint
sysml2tools help render

# Query verb overview (identical to `query --help`)
sysml2tools help query

# Query verb-specific help (identical to `query <verb> --help`)
sysml2tools help query hierarchy

Global Flags

# Display version
sysml2tools --version

# Display help
sysml2tools --help

# Run self-validation
sysml2tools --validate

# Save validation results
sysml2tools --validate --results results.trx
sysml2tools --validate --results results.xml

# Silent mode with logging
sysml2tools --silent --log output.log

Command-Line Reference

sysml2tools [-v|--version] [-?|-h|--help] [--silent]
            [--validate] [--result|--results <file>] [--depth <#>] [--log <file>]
            [<verb> [verb-options] [<globs>]]
sysml2tools help [lint|render|query [<query-verb>]]

<verb> is lint, render, or query <query-verb> (11 query verbs — see the Querying section above).

Global Options

lint Options

render Options

query Options

help Options

View Selection

For every layout strategy (not just the General View), a view's body expose <...>; statements now scope the rendered diagram to the union of the exposed names' containment subtrees, instead of always rendering the full workspace; a view with no expose statement continues to render the full workspace. render asTreeDiagram; and render asInterconnectionDiagram; now select the Browser View and Interconnection View layout strategies respectively, taking precedence over the name/supertype heuristic; other render targets (asElementTable, asTextualNotation, an unrecognized name, or none) leave strategy selection unchanged. render never affects content scope — expose remains the sole scoping mechanism regardless of which strategy is selected — see the Introduction user guide for details.

NuGet Packages

Library consumers can take a dependency on DemaConsulting.SysML2Tools.Core alone to access parsing, semantic model, and layout without pulling in the CLI tool; Core automatically pulls in Language and Stdlib as NuGet dependencies. Each package ships its own generated Markdown API reference documentation alongside its assembly.

Contributing

See CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

License

Copyright (c) DEMA Consulting. Licensed under the MIT License. See LICENSE for details.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.