|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +SysML2.NET is a .NET C# SDK implementing the OMG SysML v2 specification (based on Beta 4 pilot implementation). It provides metaclass DTOs/POCOs, serializers (JSON, XMI, MessagePack), a REST client, a DAL layer, and a Blazor WebAssembly viewer application. Current version: 0.19.0. |
| 8 | + |
| 9 | +## Build & Test Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Restore and build entire solution |
| 13 | +dotnet restore SysML2.NET.sln |
| 14 | +dotnet build SysML2.NET.sln |
| 15 | + |
| 16 | +# Run all tests |
| 17 | +dotnet test SysML2.NET.sln |
| 18 | + |
| 19 | +# Run tests for a specific project |
| 20 | +dotnet test SysML2.NET.Tests/SysML2.NET.Tests.csproj |
| 21 | +dotnet test SysML2.NET.Serializer.Json.Tests/SysML2.NET.Serializer.Json.Tests.csproj |
| 22 | + |
| 23 | +# Run a single test by name |
| 24 | +dotnet test SysML2.NET.Tests/SysML2.NET.Tests.csproj --filter "FullyQualifiedName~AcceptActionUsageExtensionsTestFixture" |
| 25 | + |
| 26 | +# Run with coverage (as CI does) |
| 27 | +dotnet-coverage collect "dotnet test SysML2.NET.sln --no-build" -f xml -o coverage.xml |
| 28 | +``` |
| 29 | + |
| 30 | +Test framework: **NUnit**. Test classes use `[TestFixture]` and `[Test]` attributes. |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +### Code Generation Pipeline |
| 35 | + |
| 36 | +Most code in this repo is **auto-generated** — files marked `THIS IS AN AUTOMATICALLY GENERATED FILE. ANY MANUAL CHANGES WILL BE OVERWRITTEN!` must not be edited directly. |
| 37 | + |
| 38 | +The pipeline: |
| 39 | +1. **Input**: `Resources/KerML_only_xmi.uml` and `Resources/SysML_only_xmi.uml` (UML XMI metamodel files) |
| 40 | +2. **Generator**: `SysML2.NET.CodeGenerator` reads these via `uml4net.xmi`, uses Handlebars templates (`Templates/Uml/*.hbs`) to generate code |
| 41 | +3. **Output**: `AutoGen*` directories across multiple projects |
| 42 | + |
| 43 | +Generator classes in `SysML2.NET.CodeGenerator/Generators/UmlHandleBarsGenerators/` produce: |
| 44 | +- DTOs and interfaces → `SysML2.NET/Core/AutoGenDto/` |
| 45 | +- POCOs → `SysML2.NET/Core/AutoGenPoco/` |
| 46 | +- Enums → `SysML2.NET/Core/AutoGenEnum/` |
| 47 | +- JSON serializers/deserializers → `SysML2.NET.Serializer.Json/Core/AutoGenSerializer/` and `AutoGenDeSerializer/` |
| 48 | +- MessagePack formatters → `SysML2.NET.Serializer.MessagePack/` |
| 49 | +- Extension methods (Extend) → `SysML2.NET/Extend/` |
| 50 | +- DAL factories → `SysML2.NET.Dal/Core/` |
| 51 | + |
| 52 | +### Project Dependency Graph |
| 53 | + |
| 54 | +``` |
| 55 | +SysML2.NET (core: netstandard2.1) |
| 56 | + ├── Core/AutoGenDto/ - 342 files: DTO classes + interfaces (171 metaclasses × 2) |
| 57 | + ├── Core/AutoGenPoco/ - POCO classes + interfaces |
| 58 | + ├── Core/AutoGenEnum/ - Enums (FeatureDirectionKind, VisibilityKind, etc.) |
| 59 | + ├── Core/DTO/ - Hand-coded base: IElement : IData |
| 60 | + ├── Core/POCO/ - Hand-coded: IContainedElement, IContainedRelationship |
| 61 | + ├── Extend/ - Auto-generated extension methods per metaclass |
| 62 | + ├── Decorators/ - [Class], [Property], [Implements] attributes from UML |
| 63 | + ├── PIM/ - Platform-Independent Model DTOs (REST API types) |
| 64 | + ├── ModelInterchange/ - Archive/project interchange types (kpar support) |
| 65 | + └── Common/IData.cs - Base interface with Id property |
| 66 | +
|
| 67 | +SysML2.NET.Extensions - Comparers, utilities across metaclasses |
| 68 | +SysML2.NET.Serializer.Json - JSON (de)serialization via System.Text.Json |
| 69 | +SysML2.NET.Serializer.Xmi - XMI (de)serialization |
| 70 | +SysML2.NET.Serializer.MessagePack - MessagePack binary serialization |
| 71 | +SysML2.NET.Serializer.Dictionary - Dictionary-based serialization (PIM) |
| 72 | +SysML2.NET.Dal - Data Access Layer (Assembler, ElementFactory) |
| 73 | +SysML2.NET.REST - REST client + Session for SysML2 API servers |
| 74 | +SysML2.NET.Kpar - Reader/Writer for .kpar archive format |
| 75 | +SysML2.NET.Viewer - Blazor WebAssembly app (net9.0) |
| 76 | +SysML2.NET.CodeGenerator - Code generation tool (net10.0, not packaged) |
| 77 | +``` |
| 78 | + |
| 79 | +### DTO vs POCO Pattern |
| 80 | + |
| 81 | +Each metaclass exists in two forms: |
| 82 | +- **DTO** (Data Transfer Object): Lightweight, uses `Guid` references for relationships. Used for serialization/transport. Properties reference other elements by `Guid` ID. |
| 83 | +- **POCO** (Plain Old CLR Object): Rich object model with resolved object references. Used for in-memory manipulation. Uses `ContainerList<T>` for containment relationships. |
| 84 | + |
| 85 | +Both share the same `I{MetaclassName}` interface from `AutoGenDto/`. The hand-coded `Core/DTO/IElement.cs` adds `IData` (which provides `Guid Id`) to the root interface. |
| 86 | + |
| 87 | +### Namespace Convention |
| 88 | + |
| 89 | +Auto-generated DTOs use structured namespaces reflecting the KerML/SysML package hierarchy: |
| 90 | +- `SysML2.NET.Core.DTO.Root.Elements` (Element, Annotation, etc.) |
| 91 | +- `SysML2.NET.Core.DTO.Core.Types` (Type, Feature, Classifier, etc.) |
| 92 | +- `SysML2.NET.Core.DTO.Systems.Actions` (ActionUsage, etc.) |
| 93 | + |
| 94 | +### Target Frameworks |
| 95 | + |
| 96 | +- Core library (`SysML2.NET`): `netstandard2.1` |
| 97 | +- Test projects and CodeGenerator: `net10.0` |
| 98 | +- Viewer: `net9.0` (Blazor WebAssembly) |
| 99 | + |
| 100 | +## Key Conventions |
| 101 | + |
| 102 | +- Commit messages use prefix tags: `[Add]`, `[Update]`, `[Remove]`, `[Fix]` |
| 103 | +- Main branch: `master`. Development branch: `development` |
| 104 | +- CI: GitHub Actions (`CodeQuality.yml`) — builds, tests, and runs SonarQube analysis |
| 105 | +- License: Apache 2.0 (code), LGPL v3.0 (metamodel files) |
| 106 | +- To add a new metaclass: update the UML XMI source files, then run the code generators — do not manually create AutoGen files |
0 commit comments