From eba79d484cf41efa9c8c70b4bfac48864f8e2a4d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 14 Jul 2026 14:10:27 -0400 Subject: [PATCH 1/3] Replace comment-block metadata with structured SoftwareInfo, fix namespace hierarchy - Add docs/sysml2/common/software-items.sysml defining SoftwareItemMetadata::SoftwareInfo, a reusable metadata type (description, sourceFiles, testFiles, designFiles, verificationFiles, requirementFiles - all [0..1]/[0..*]) replacing the ad-hoc comment/doc blocks an unfamiliar-with-SysML authoring agent had added, which were rendering as note-box clutter on every diagram. - Remove all doc/comment annotations from model definitions; fold their text into SoftwareInfo's new description attribute instead, so diagrams now show pure structural boxes (System/Subsystem/Unit) with zero note-box splatter. Metadata is invisible to rendering but remains fully queryable via filter/query/export. - Restructure the VersionMark model from a flat package VersionMark { ... } reopened across every file into genuine nested package VersionMark { package Cli { ... } } (etc. for Configuration/Capture/Publishing/SelfTest/Utilities), matching the existing folder layout and fixing expose VersionMark::*; semantics (previously every leaf definition was a false "direct child" of VersionMark). - Update SoftwareStructureView to expose VersionMark::**; (whole subtree) since subsystem definitions are no longer direct children of VersionMark. - Bump the pinned demaconsulting.sysml2tools.tool version from 0.1.0-beta.7 to the published 0.1.0-beta.8, matching the recursion-scoping fix this rework relies on. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 2 +- docs/sysml2/common/software-items.sysml | 18 ++++++++++ docs/sysml2/model/ots.sysml | 35 +++++++++++-------- docs/sysml2/model/version-mark.sysml | 25 +++++++++---- docs/sysml2/model/version-mark/capture.sysml | 19 ++++++---- .../version-mark/capture/version-info.sysml | 19 ++++++---- docs/sysml2/model/version-mark/cli.sysml | 21 ++++++----- .../model/version-mark/cli/context.sysml | 19 ++++++---- .../model/version-mark/cli/program.sysml | 19 ++++++---- .../model/version-mark/configuration.sysml | 23 +++++++----- .../configuration/lint-issue.sysml | 19 ++++++---- .../configuration/tool-config.sysml | 19 ++++++---- .../configuration/version-mark-config.sysml | 25 +++++++++---- .../model/version-mark/publishing.sysml | 19 ++++++---- .../publishing/markdown-formatter.sysml | 19 ++++++---- .../sysml2/model/version-mark/self-test.sysml | 19 ++++++---- .../version-mark/self-test/validation.sysml | 19 ++++++---- .../sysml2/model/version-mark/utilities.sysml | 19 ++++++---- .../version-mark/utilities/glob-matcher.sysml | 19 ++++++---- .../version-mark/utilities/path-helpers.sysml | 19 ++++++---- docs/sysml2/views/design-views.sysml | 12 ++++++- 21 files changed, 270 insertions(+), 138 deletions(-) create mode 100644 docs/sysml2/common/software-items.sysml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 606edd2..779509e 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -63,7 +63,7 @@ ] }, "demaconsulting.sysml2tools.tool": { - "version": "0.1.0-beta.7", + "version": "0.1.0-beta.8", "commands": [ "sysml2tools" ] diff --git a/docs/sysml2/common/software-items.sysml b/docs/sysml2/common/software-items.sysml new file mode 100644 index 0000000..8c6ce93 --- /dev/null +++ b/docs/sysml2/common/software-items.sysml @@ -0,0 +1,18 @@ +// Shared metadata definitions for annotating software-item model elements with traceability +// links to their supporting project artifacts (source, test, design, verification, requirements). +// Intended to be reused as-is across multiple DEMA Consulting repositories - keep this package +// self-contained (no repo-specific imports) so it can be copied/synced without modification. +package SoftwareItemMetadata { + private import ScalarValues::String; + + metadata def SoftwareInfo { + doc /* Traceability links from a model element to its supporting project artifacts. */ + + attribute description : String [0..1]; + attribute sourceFiles : String [0..*]; + attribute testFiles : String [0..*]; + attribute designFiles : String [0..*]; + attribute verificationFiles : String [0..*]; + attribute requirementFiles : String [0..*]; + } +} diff --git a/docs/sysml2/model/ots.sysml b/docs/sysml2/model/ots.sysml index 62a9390..ef70c96 100644 --- a/docs/sysml2/model/ots.sysml +++ b/docs/sysml2/model/ots.sysml @@ -1,27 +1,32 @@ package OtsDependencies { + private import SoftwareItemMetadata::*; + doc /* Off-the-shelf (OTS) runtime dependencies used by VersionMark. */ part def YamlDotNet { - doc /* OTS: YamlDotNet. */ - - comment designRef /* Design: docs/design/ots/yaml-dot-net.md */ - comment verificationRef /* Verification: docs/verification/ots/yaml-dot-net.md */ - comment reqRef /* Requirements: docs/reqstream/ots/yaml-dot-net.yaml */ + metadata info : SoftwareInfo { + description = "OTS: YamlDotNet."; + designFiles = ("docs/design/ots/yaml-dot-net.md"); + verificationFiles = ("docs/verification/ots/yaml-dot-net.md"); + requirementFiles = ("docs/reqstream/ots/yaml-dot-net.yaml"); + } } part def FileSystemGlobbing { - doc /* OTS: Microsoft.Extensions.FileSystemGlobbing. */ - - comment designRef /* Design: docs/design/ots/microsoft-extensions-file-system-globbing.md */ - comment verificationRef /* Verification: docs/verification/ots/microsoft-extensions-file-system-globbing.md */ - comment reqRef /* Requirements: docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml */ + metadata info : SoftwareInfo { + description = "OTS: Microsoft.Extensions.FileSystemGlobbing."; + designFiles = ("docs/design/ots/microsoft-extensions-file-system-globbing.md"); + verificationFiles = ("docs/verification/ots/microsoft-extensions-file-system-globbing.md"); + requirementFiles = ("docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml"); + } } part def TestResults { - doc /* OTS: DemaConsulting.TestResults. */ - - comment designRef /* Design: docs/design/ots/dema-consulting-test-results.md */ - comment verificationRef /* Verification: docs/verification/ots/dema-consulting-test-results.md */ - comment reqRef /* Requirements: docs/reqstream/ots/dema-consulting-test-results.yaml */ + metadata info : SoftwareInfo { + description = "OTS: DemaConsulting.TestResults."; + designFiles = ("docs/design/ots/dema-consulting-test-results.md"); + verificationFiles = ("docs/verification/ots/dema-consulting-test-results.md"); + requirementFiles = ("docs/reqstream/ots/dema-consulting-test-results.yaml"); + } } } diff --git a/docs/sysml2/model/version-mark.sysml b/docs/sysml2/model/version-mark.sysml index cfe2efa..dbc312d 100644 --- a/docs/sysml2/model/version-mark.sysml +++ b/docs/sysml2/model/version-mark.sysml @@ -1,5 +1,17 @@ package VersionMark { import OtsDependencies::*; + private import SoftwareItemMetadata::*; + + // Each subsystem now lives in its own VersionMark:: nested package (see + // version-mark/*.sysml) rather than being flattened directly into VersionMark, so this system + // definition needs an explicit import per subsystem to reference its subsystem part def by + // simple name below. + import VersionMark::Cli::*; + import VersionMark::Configuration::*; + import VersionMark::Capture::*; + import VersionMark::Publishing::*; + import VersionMark::SelfTest::*; + import VersionMark::Utilities::*; doc /* @@ -8,12 +20,13 @@ package VersionMark { */ part def VersionMarkSystem { - doc /* The VersionMark system as a whole. */ - - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/IntegrationTests.cs */ - comment designRef /* Design: docs/design/version-mark.md */ - comment verificationRef /* Verification: docs/verification/version-mark.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark.yaml */ + metadata info : SoftwareInfo { + description = "The VersionMark system as a whole."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/IntegrationTests.cs"); + designFiles = ("docs/design/version-mark.md"); + verificationFiles = ("docs/verification/version-mark.md"); + requirementFiles = ("docs/reqstream/version-mark.yaml"); + } part cli : CliSubsystem; part configuration : ConfigurationSubsystem; diff --git a/docs/sysml2/model/version-mark/capture.sysml b/docs/sysml2/model/version-mark/capture.sysml index 58de543..cea33f2 100644 --- a/docs/sysml2/model/version-mark/capture.sysml +++ b/docs/sysml2/model/version-mark/capture.sysml @@ -1,12 +1,17 @@ package VersionMark { - part def CaptureSubsystem { - doc /* JSON serialization of captured version data. */ + package Capture { + private import SoftwareItemMetadata::*; - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Capture/CaptureTests.cs */ - comment designRef /* Design: docs/design/version-mark/capture.md */ - comment verificationRef /* Verification: docs/verification/version-mark/capture.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/capture.yaml */ + part def CaptureSubsystem { + metadata info : SoftwareInfo { + description = "JSON serialization of captured version data."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/CaptureTests.cs"); + designFiles = ("docs/design/version-mark/capture.md"); + verificationFiles = ("docs/verification/version-mark/capture.md"); + requirementFiles = ("docs/reqstream/version-mark/capture.yaml"); + } - part versionInfo : VersionInfo; + part versionInfo : VersionInfo; + } } } diff --git a/docs/sysml2/model/version-mark/capture/version-info.sysml b/docs/sysml2/model/version-mark/capture/version-info.sysml index 0ab39e4..d156892 100644 --- a/docs/sysml2/model/version-mark/capture/version-info.sysml +++ b/docs/sysml2/model/version-mark/capture/version-info.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def VersionInfo { - doc /* Captured version record; JSON serialization for capture/publish handoff. */ + package Capture { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Capture/VersionInfo.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Capture/VersionInfoTests.cs */ - comment designRef /* Design: docs/design/version-mark/capture/version-info.md */ - comment verificationRef /* Verification: docs/verification/version-mark/capture/version-info.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/capture/version-info.yaml */ + part def VersionInfo { + metadata info : SoftwareInfo { + description = "Captured version record; JSON serialization for capture/publish handoff."; + sourceFiles = ("src/DemaConsulting.VersionMark/Capture/VersionInfo.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/VersionInfoTests.cs"); + designFiles = ("docs/design/version-mark/capture/version-info.md"); + verificationFiles = ("docs/verification/version-mark/capture/version-info.md"); + requirementFiles = ("docs/reqstream/version-mark/capture/version-info.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/cli.sysml b/docs/sysml2/model/version-mark/cli.sysml index 3724399..c30b37e 100644 --- a/docs/sysml2/model/version-mark/cli.sysml +++ b/docs/sysml2/model/version-mark/cli.sysml @@ -1,13 +1,18 @@ package VersionMark { - part def CliSubsystem { - doc /* Command-line argument parsing, mode dispatch, and output routing. */ + package Cli { + private import SoftwareItemMetadata::*; - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Cli/CliTests.cs */ - comment designRef /* Design: docs/design/version-mark/cli.md */ - comment verificationRef /* Verification: docs/verification/version-mark/cli.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/cli.yaml */ + part def CliSubsystem { + metadata info : SoftwareInfo { + description = "Command-line argument parsing, mode dispatch, and output routing."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/CliTests.cs"); + designFiles = ("docs/design/version-mark/cli.md"); + verificationFiles = ("docs/verification/version-mark/cli.md"); + requirementFiles = ("docs/reqstream/version-mark/cli.yaml"); + } - part program : Program; - part context : Context; + part program : Program; + part context : Context; + } } } diff --git a/docs/sysml2/model/version-mark/cli/context.sysml b/docs/sysml2/model/version-mark/cli/context.sysml index 8dd2fba..c2c5428 100644 --- a/docs/sysml2/model/version-mark/cli/context.sysml +++ b/docs/sysml2/model/version-mark/cli/context.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def Context { - doc /* Command-line argument and output container (console, error, log file). */ + package Cli { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Cli/Context.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs */ - comment designRef /* Design: docs/design/version-mark/cli/context.md */ - comment verificationRef /* Verification: docs/verification/version-mark/cli/context.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/cli/context.yaml */ + part def Context { + metadata info : SoftwareInfo { + description = "Command-line argument and output container (console, error, log file)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Cli/Context.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs"); + designFiles = ("docs/design/version-mark/cli/context.md"); + verificationFiles = ("docs/verification/version-mark/cli/context.md"); + requirementFiles = ("docs/reqstream/version-mark/cli/context.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/cli/program.sysml b/docs/sysml2/model/version-mark/cli/program.sysml index 5f737a4..2b2af3c 100644 --- a/docs/sysml2/model/version-mark/cli/program.sysml +++ b/docs/sysml2/model/version-mark/cli/program.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def Program { - doc /* Entry point and mode dispatcher (capture, publish, lint, validate). */ + package Cli { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Program.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/ProgramTests.cs */ - comment designRef /* Design: docs/design/version-mark/cli/program.md */ - comment verificationRef /* Verification: docs/verification/version-mark/cli/program.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/cli/program.yaml */ + part def Program { + metadata info : SoftwareInfo { + description = "Entry point and mode dispatcher (capture, publish, lint, validate)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Program.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/ProgramTests.cs"); + designFiles = ("docs/design/version-mark/cli/program.md"); + verificationFiles = ("docs/verification/version-mark/cli/program.md"); + requirementFiles = ("docs/reqstream/version-mark/cli/program.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/configuration.sysml b/docs/sysml2/model/version-mark/configuration.sysml index c40c8c2..a2faed8 100644 --- a/docs/sysml2/model/version-mark/configuration.sysml +++ b/docs/sysml2/model/version-mark/configuration.sysml @@ -1,14 +1,19 @@ package VersionMark { - part def ConfigurationSubsystem { - doc /* YAML configuration loading, validation, and version capture execution. */ + package Configuration { + private import SoftwareItemMetadata::*; - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/ConfigurationTests.cs */ - comment designRef /* Design: docs/design/version-mark/configuration.md */ - comment verificationRef /* Verification: docs/verification/version-mark/configuration.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/configuration.yaml */ + part def ConfigurationSubsystem { + metadata info : SoftwareInfo { + description = "YAML configuration loading, validation, and version capture execution."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/ConfigurationTests.cs"); + designFiles = ("docs/design/version-mark/configuration.md"); + verificationFiles = ("docs/verification/version-mark/configuration.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration.yaml"); + } - part versionMarkConfig : VersionMarkConfig; - part toolConfig : ToolConfig; - part lintIssue : LintIssue; + part versionMarkConfig : VersionMarkConfig; + part toolConfig : ToolConfig; + part lintIssue : LintIssue; + } } } diff --git a/docs/sysml2/model/version-mark/configuration/lint-issue.sysml b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml index c287a74..faa34f9 100644 --- a/docs/sysml2/model/version-mark/configuration/lint-issue.sysml +++ b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def LintIssue { - doc /* Represents a single configuration validation issue with source location. */ + package Configuration { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/LintIssue.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/LintIssueTests.cs */ - comment designRef /* Design: docs/design/version-mark/configuration/lint-issue.md */ - comment verificationRef /* Verification: docs/verification/version-mark/configuration/lint-issue.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/lint-issue.yaml */ + part def LintIssue { + metadata info : SoftwareInfo { + description = "Represents a single configuration validation issue with source location."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/LintIssue.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/LintIssueTests.cs"); + designFiles = ("docs/design/version-mark/configuration/lint-issue.md"); + verificationFiles = ("docs/verification/version-mark/configuration/lint-issue.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration/lint-issue.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/configuration/tool-config.sysml b/docs/sysml2/model/version-mark/configuration/tool-config.sysml index cf77a4d..e8c68db 100644 --- a/docs/sysml2/model/version-mark/configuration/tool-config.sysml +++ b/docs/sysml2/model/version-mark/configuration/tool-config.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def ToolConfig { - doc /* Per-tool capture configuration (command, regex, OS-specific overrides). */ + package Configuration { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs (ToolConfig record; no dedicated file) */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs */ - comment designRef /* Design: docs/design/version-mark/configuration/tool-config.md */ - comment verificationRef /* Verification: docs/verification/version-mark/configuration/tool-config.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/tool-config.yaml */ + part def ToolConfig { + metadata info : SoftwareInfo { + description = "Per-tool capture configuration (command, regex, OS-specific overrides)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs"); + designFiles = ("docs/design/version-mark/configuration/tool-config.md"); + verificationFiles = ("docs/verification/version-mark/configuration/tool-config.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration/tool-config.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml index 72f8734..75b7293 100644 --- a/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml +++ b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml @@ -1,11 +1,22 @@ package VersionMark { - part def VersionMarkConfig { - doc /* Loads, validates, and executes `.versionmark.yaml` tool version capture. */ + package Configuration { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs (also see VersionMarkConfigLoadTests.cs) */ - comment designRef /* Design: docs/design/version-mark/configuration/version-mark-config.md */ - comment verificationRef /* Verification: docs/verification/version-mark/configuration/version-mark-config.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/version-mark-config.yaml (also load.yaml for VersionMarkConfig.Load behavior) */ + part def VersionMarkConfig { + metadata info : SoftwareInfo { + description = "Loads, validates, and executes `.versionmark.yaml` tool version capture."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); + testFiles = ( + "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs", + "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigLoadTests.cs" + ); + designFiles = ("docs/design/version-mark/configuration/version-mark-config.md"); + verificationFiles = ("docs/verification/version-mark/configuration/version-mark-config.md"); + requirementFiles = ( + "docs/reqstream/version-mark/configuration/version-mark-config.yaml", + "docs/reqstream/version-mark/configuration/load.yaml" + ); + } + } } } diff --git a/docs/sysml2/model/version-mark/publishing.sysml b/docs/sysml2/model/version-mark/publishing.sysml index ce44e71..e17a184 100644 --- a/docs/sysml2/model/version-mark/publishing.sysml +++ b/docs/sysml2/model/version-mark/publishing.sysml @@ -1,12 +1,17 @@ package VersionMark { - part def PublishingSubsystem { - doc /* Markdown report generation from captured version data. */ + package Publishing { + private import SoftwareItemMetadata::*; - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Publishing/PublishingTests.cs */ - comment designRef /* Design: docs/design/version-mark/publishing.md */ - comment verificationRef /* Verification: docs/verification/version-mark/publishing.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/publishing.yaml */ + part def PublishingSubsystem { + metadata info : SoftwareInfo { + description = "Markdown report generation from captured version data."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/PublishingTests.cs"); + designFiles = ("docs/design/version-mark/publishing.md"); + verificationFiles = ("docs/verification/version-mark/publishing.md"); + requirementFiles = ("docs/reqstream/version-mark/publishing.yaml"); + } - part markdownFormatter : MarkdownFormatter; + part markdownFormatter : MarkdownFormatter; + } } } diff --git a/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml index 9e60770..d0af269 100644 --- a/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml +++ b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def MarkdownFormatter { - doc /* Converts loaded version records into a consolidated markdown report. */ + package Publishing { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Publishing/MarkdownFormatter.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Publishing/MarkdownFormatterTests.cs */ - comment designRef /* Design: docs/design/version-mark/publishing/markdown-formatter.md */ - comment verificationRef /* Verification: docs/verification/version-mark/publishing/markdown-formatter.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/publishing/markdown-formatter.yaml */ + part def MarkdownFormatter { + metadata info : SoftwareInfo { + description = "Converts loaded version records into a consolidated markdown report."; + sourceFiles = ("src/DemaConsulting.VersionMark/Publishing/MarkdownFormatter.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/MarkdownFormatterTests.cs"); + designFiles = ("docs/design/version-mark/publishing/markdown-formatter.md"); + verificationFiles = ("docs/verification/version-mark/publishing/markdown-formatter.md"); + requirementFiles = ("docs/reqstream/version-mark/publishing/markdown-formatter.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/self-test.sysml b/docs/sysml2/model/version-mark/self-test.sysml index 9b35bdc..cbaa04e 100644 --- a/docs/sysml2/model/version-mark/self-test.sysml +++ b/docs/sysml2/model/version-mark/self-test.sysml @@ -1,12 +1,17 @@ package VersionMark { - part def SelfTestSubsystem { - doc /* Built-in self-verification of all operational modes. */ + package SelfTest { + private import SoftwareItemMetadata::*; - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs */ - comment designRef /* Design: docs/design/version-mark/self-test.md */ - comment verificationRef /* Verification: docs/verification/version-mark/self-test.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/self-test.yaml */ + part def SelfTestSubsystem { + metadata info : SoftwareInfo { + description = "Built-in self-verification of all operational modes."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); + designFiles = ("docs/design/version-mark/self-test.md"); + verificationFiles = ("docs/verification/version-mark/self-test.md"); + requirementFiles = ("docs/reqstream/version-mark/self-test.yaml"); + } - part validation : Validation; + part validation : Validation; + } } } diff --git a/docs/sysml2/model/version-mark/self-test/validation.sysml b/docs/sysml2/model/version-mark/self-test/validation.sysml index 95f411b..58dc46a 100644 --- a/docs/sysml2/model/version-mark/self-test/validation.sysml +++ b/docs/sysml2/model/version-mark/self-test/validation.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def Validation { - doc /* Exercises capture, publish, and lint modes end-to-end for self-validation. */ + package SelfTest { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/SelfTest/Validation.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs (no dedicated ValidationTests.cs) */ - comment designRef /* Design: docs/design/version-mark/self-test/validation.md */ - comment verificationRef /* Verification: docs/verification/version-mark/self-test/validation.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/self-test/validation.yaml */ + part def Validation { + metadata info : SoftwareInfo { + description = "Exercises capture, publish, and lint modes end-to-end for self-validation."; + sourceFiles = ("src/DemaConsulting.VersionMark/SelfTest/Validation.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); + designFiles = ("docs/design/version-mark/self-test/validation.md"); + verificationFiles = ("docs/verification/version-mark/self-test/validation.md"); + requirementFiles = ("docs/reqstream/version-mark/self-test/validation.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/utilities.sysml b/docs/sysml2/model/version-mark/utilities.sysml index 74f2f12..ddac813 100644 --- a/docs/sysml2/model/version-mark/utilities.sysml +++ b/docs/sysml2/model/version-mark/utilities.sysml @@ -1,12 +1,17 @@ package VersionMark { - part def UtilitiesSubsystem { - doc /* Glob-pattern matching and safe path combination helpers. */ + package Utilities { + private import SoftwareItemMetadata::*; - comment designRef /* Design: docs/design/version-mark/utilities.md */ - comment verificationRef /* Verification: docs/verification/version-mark/utilities.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/utilities.yaml */ + part def UtilitiesSubsystem { + metadata info : SoftwareInfo { + description = "Glob-pattern matching and safe path combination helpers."; + designFiles = ("docs/design/version-mark/utilities.md"); + verificationFiles = ("docs/verification/version-mark/utilities.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities.yaml"); + } - part globMatcher : GlobMatcher; - part pathHelpers : PathHelpers; + part globMatcher : GlobMatcher; + part pathHelpers : PathHelpers; + } } } diff --git a/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml index f8b8a4b..28f8996 100644 --- a/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml +++ b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def GlobMatcher { - doc /* Resolves glob patterns into concrete file path lists for publish mode. */ + package Utilities { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Utilities/GlobMatcher.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Utilities/GlobMatcherTests.cs */ - comment designRef /* Design: docs/design/version-mark/utilities/glob-matcher.md */ - comment verificationRef /* Verification: docs/verification/version-mark/utilities/glob-matcher.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/utilities/glob-matcher.yaml */ + part def GlobMatcher { + metadata info : SoftwareInfo { + description = "Resolves glob patterns into concrete file path lists for publish mode."; + sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/GlobMatcher.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/GlobMatcherTests.cs"); + designFiles = ("docs/design/version-mark/utilities/glob-matcher.md"); + verificationFiles = ("docs/verification/version-mark/utilities/glob-matcher.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities/glob-matcher.yaml"); + } + } } } diff --git a/docs/sysml2/model/version-mark/utilities/path-helpers.sysml b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml index ac40370..91290b7 100644 --- a/docs/sysml2/model/version-mark/utilities/path-helpers.sysml +++ b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml @@ -1,11 +1,16 @@ package VersionMark { - part def PathHelpers { - doc /* Safe path combination helpers used to construct paths within temp directories. */ + package Utilities { + private import SoftwareItemMetadata::*; - comment sourceRef /* Source: src/DemaConsulting.VersionMark/Utilities/PathHelpers.cs */ - comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Utilities/PathHelpersTests.cs */ - comment designRef /* Design: docs/design/version-mark/utilities/path-helpers.md */ - comment verificationRef /* Verification: docs/verification/version-mark/utilities/path-helpers.md */ - comment reqRef /* Requirements: docs/reqstream/version-mark/utilities/path-helpers.yaml */ + part def PathHelpers { + metadata info : SoftwareInfo { + description = "Safe path combination helpers used to construct paths within temp directories."; + sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/PathHelpers.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/PathHelpersTests.cs"); + designFiles = ("docs/design/version-mark/utilities/path-helpers.md"); + verificationFiles = ("docs/verification/version-mark/utilities/path-helpers.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities/path-helpers.yaml"); + } + } } } diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml index 24041bf..dfc0900 100644 --- a/docs/sysml2/views/design-views.sysml +++ b/docs/sysml2/views/design-views.sysml @@ -4,8 +4,18 @@ // inside a named 'view' usage (not a 'view def' definition), and it - not // 'render' - is what scopes the rendered diagram content. package VersionMark { + // Each subsystem now lives in its own VersionMark:: nested package (see + // docs/sysml2/model/version-mark/*.sysml), so the per-subsystem views below need an + // explicit import per subsystem to reference each subsystem part def by simple name. + import VersionMark::Cli::*; + import VersionMark::Configuration::*; + import VersionMark::Capture::*; + import VersionMark::Publishing::*; + import VersionMark::SelfTest::*; + import VersionMark::Utilities::*; + view SoftwareStructureView { - expose VersionMark; + expose VersionMark::**; } view VersionMarkView { From 9a84044a4cdf51ba84d31955bfff69469d2ce4a1 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sun, 19 Jul 2026 12:53:05 -0400 Subject: [PATCH 2/3] Model real SysML dependency relationships instead of hand-drawn DependencyView diagrams Replaces the earlier flawed, manually-drawn DependencyView diagrams with genuine SysML v2 `dependency` relationships declared directly on each unit, rendered automatically via existing InterconnectionView machinery. - Bump pinned sysml2tools tool 0.1.0-beta.8 -> 0.1.0-beta.12. - Flatten the nested `package Cli { ... }`-style wrappers introduced by the SoftwareInfo metadata restructuring back to single reopened `package VersionMark { ... }` blocks per file, so cross-file `dependency` statements can reference collaborator simple names directly. - Add `dependency X to Y;` relationships to every unit reflecting its real collaborators (e.g. Program -> Context/VersionMarkConfig/VersionInfo/ MarkdownFormatter/GlobMatcher/Validation; GlobMatcher -> FileSystemGlobbing), making dependencies first-class, queryable model content instead of static diagrams that go stale. - Add attribute definitions to LintIssue, ToolConfig, and VersionInfo that mirror their actual C# class shapes (filePath/line/column/severity/ description, key/value pairs, jobId/versions_key/versions_value). - Update design-views.sysml: rename VersionMarkView -> VersionMarkSystemView, add `render asInterconnectionDiagram` and `expose *Subsystem::*` to every view so the new dependency edges render automatically, switch the shared import to OtsDependencies::*. - Consolidate the CI render glob (build.yaml) and sysml2-modeling.md standard from two separate patterns to a single `docs/sysml2/**/*.sysml`, fixing a gap where docs/sysml2/common/ metadata definitions were never included. Verified: build.ps1 green (244 tests x3 TFMs), sysml2tools beta.12 restored, and `sysml2tools render docs/sysml2/**/*.sysml` produces all 8 views with zero diagnostics. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 4 +- .github/standards/sysml2-modeling.md | 17 ++++---- .github/workflows/build.yaml | 3 +- docs/sysml2/model/version-mark.sysml | 11 ----- docs/sysml2/model/version-mark/capture.sysml | 22 +++++----- .../version-mark/capture/version-info.sysml | 28 +++++++----- docs/sysml2/model/version-mark/cli.sysml | 24 +++++------ .../model/version-mark/cli/context.sysml | 20 ++++----- .../model/version-mark/cli/program.sysml | 28 +++++++----- .../model/version-mark/configuration.sysml | 26 ++++++----- .../configuration/lint-issue.sysml | 36 +++++++++++----- .../configuration/tool-config.sysml | 33 +++++++++----- .../configuration/version-mark-config.sysml | 43 +++++++++++-------- .../model/version-mark/publishing.sysml | 22 +++++----- .../publishing/markdown-formatter.sysml | 23 +++++----- .../sysml2/model/version-mark/self-test.sysml | 22 +++++----- .../version-mark/self-test/validation.sysml | 29 ++++++++----- .../sysml2/model/version-mark/utilities.sysml | 22 +++++----- .../version-mark/utilities/glob-matcher.sysml | 24 ++++++----- .../version-mark/utilities/path-helpers.sysml | 20 ++++----- docs/sysml2/views/design-views.sysml | 27 +++++++----- 21 files changed, 260 insertions(+), 224 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 779509e..c22086a 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -63,10 +63,10 @@ ] }, "demaconsulting.sysml2tools.tool": { - "version": "0.1.0-beta.8", + "version": "0.1.0-beta.12", "commands": [ "sysml2tools" ] } } -} \ No newline at end of file +} diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md index c5558e1..1d5fab1 100644 --- a/.github/standards/sysml2-modeling.md +++ b/.github/standards/sysml2-modeling.md @@ -161,15 +161,16 @@ whichever produces a single coherent overview diagram. ## Diagram Embedding -Render with a single quoted recursive glob for the model tree, plus the views file +Render with a single quoted recursive glob covering the entire `docs/sysml2/` tree (`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing -or explicit per-file listing is needed): +or explicit per-file listing is needed). Use one glob rooted at `docs/sysml2/`, not just +`docs/sysml2/model/**`, so shared definitions under `docs/sysml2/common/` (e.g. metadata +defs) are always included: ```pwsh dotnet sysml2tools render ` --output docs/design/generated --format svg ` - 'docs/sysml2/model/**/*.sysml' ` - 'docs/sysml2/views/design-views.sysml' + 'docs/sysml2/**/*.sysml' ``` With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view @@ -198,10 +199,10 @@ subsection, e.g. `![{Name} Structure]({ViewName}.svg)`. `Get-ChildItem`/shell-side globbing is needed. - The CI design-document job renders the views (see the render command above) before running Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds - are unnecessary since view names are stable by definition. Pass the model and views globs as - separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`) - — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar` - workaround is needed. + are unnecessary since view names are stable by definition. Pass a single recursive glob + rooted at `docs/sysml2/` (e.g. `'docs/sysml2/**/*.sysml'`) so shared definitions outside + `model/` (such as `docs/sysml2/common/`) are always included — plain PowerShell (the default + shell) is sufficient; no `shell: bash`/`shopt -s globstar` workaround is needed. - Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to `.versionmark.yaml`'s captured tool list. diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index b5fc11d..a438087 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -749,8 +749,7 @@ jobs: run: > dotnet sysml2tools render --output docs/design/generated --format svg - 'docs/sysml2/model/**/*.sysml' - 'docs/sysml2/views/design-views.sysml' + 'docs/sysml2/**/*.sysml' - name: Generate Design HTML with Pandoc shell: bash diff --git a/docs/sysml2/model/version-mark.sysml b/docs/sysml2/model/version-mark.sysml index dbc312d..c5ba612 100644 --- a/docs/sysml2/model/version-mark.sysml +++ b/docs/sysml2/model/version-mark.sysml @@ -2,17 +2,6 @@ package VersionMark { import OtsDependencies::*; private import SoftwareItemMetadata::*; - // Each subsystem now lives in its own VersionMark:: nested package (see - // version-mark/*.sysml) rather than being flattened directly into VersionMark, so this system - // definition needs an explicit import per subsystem to reference its subsystem part def by - // simple name below. - import VersionMark::Cli::*; - import VersionMark::Configuration::*; - import VersionMark::Capture::*; - import VersionMark::Publishing::*; - import VersionMark::SelfTest::*; - import VersionMark::Utilities::*; - doc /* * VersionMark is a .NET global tool that captures tool/dependency versions, diff --git a/docs/sysml2/model/version-mark/capture.sysml b/docs/sysml2/model/version-mark/capture.sysml index cea33f2..5e4dcca 100644 --- a/docs/sysml2/model/version-mark/capture.sysml +++ b/docs/sysml2/model/version-mark/capture.sysml @@ -1,17 +1,15 @@ package VersionMark { - package Capture { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def CaptureSubsystem { - metadata info : SoftwareInfo { - description = "JSON serialization of captured version data."; - testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/CaptureTests.cs"); - designFiles = ("docs/design/version-mark/capture.md"); - verificationFiles = ("docs/verification/version-mark/capture.md"); - requirementFiles = ("docs/reqstream/version-mark/capture.yaml"); - } - - part versionInfo : VersionInfo; + part def CaptureSubsystem { + metadata info : SoftwareInfo { + description = "JSON serialization of captured version data."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/CaptureTests.cs"); + designFiles = ("docs/design/version-mark/capture.md"); + verificationFiles = ("docs/verification/version-mark/capture.md"); + requirementFiles = ("docs/reqstream/version-mark/capture.yaml"); } + + part versionInfo : VersionInfo; } } diff --git a/docs/sysml2/model/version-mark/capture/version-info.sysml b/docs/sysml2/model/version-mark/capture/version-info.sysml index d156892..b414f15 100644 --- a/docs/sysml2/model/version-mark/capture/version-info.sysml +++ b/docs/sysml2/model/version-mark/capture/version-info.sysml @@ -1,16 +1,22 @@ package VersionMark { - package Capture { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + private import ScalarValues::String; - part def VersionInfo { - metadata info : SoftwareInfo { - description = "Captured version record; JSON serialization for capture/publish handoff."; - sourceFiles = ("src/DemaConsulting.VersionMark/Capture/VersionInfo.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/VersionInfoTests.cs"); - designFiles = ("docs/design/version-mark/capture/version-info.md"); - verificationFiles = ("docs/verification/version-mark/capture/version-info.md"); - requirementFiles = ("docs/reqstream/version-mark/capture/version-info.yaml"); - } + part def VersionInfo { + metadata info : SoftwareInfo { + description = "Captured version record; JSON serialization for capture/publish handoff."; + sourceFiles = ("src/DemaConsulting.VersionMark/Capture/VersionInfo.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Capture/VersionInfoTests.cs"); + designFiles = ("docs/design/version-mark/capture/version-info.md"); + verificationFiles = ("docs/verification/version-mark/capture/version-info.md"); + requirementFiles = ("docs/reqstream/version-mark/capture/version-info.yaml"); } + + attribute jobId : String; + + // Captured tool versions dictionary (Dictionary in code), split into + // parallel key/value lists since a native map attribute is not representable here. + attribute versions_key : String [0..*]; + attribute versions_value : String [0..*]; } } diff --git a/docs/sysml2/model/version-mark/cli.sysml b/docs/sysml2/model/version-mark/cli.sysml index c30b37e..97759df 100644 --- a/docs/sysml2/model/version-mark/cli.sysml +++ b/docs/sysml2/model/version-mark/cli.sysml @@ -1,18 +1,16 @@ package VersionMark { - package Cli { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def CliSubsystem { - metadata info : SoftwareInfo { - description = "Command-line argument parsing, mode dispatch, and output routing."; - testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/CliTests.cs"); - designFiles = ("docs/design/version-mark/cli.md"); - verificationFiles = ("docs/verification/version-mark/cli.md"); - requirementFiles = ("docs/reqstream/version-mark/cli.yaml"); - } - - part program : Program; - part context : Context; + part def CliSubsystem { + metadata info : SoftwareInfo { + description = "Command-line argument parsing, mode dispatch, and output routing."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/CliTests.cs"); + designFiles = ("docs/design/version-mark/cli.md"); + verificationFiles = ("docs/verification/version-mark/cli.md"); + requirementFiles = ("docs/reqstream/version-mark/cli.yaml"); } + + part program : Program; + part context : Context; } } diff --git a/docs/sysml2/model/version-mark/cli/context.sysml b/docs/sysml2/model/version-mark/cli/context.sysml index c2c5428..ca95e0c 100644 --- a/docs/sysml2/model/version-mark/cli/context.sysml +++ b/docs/sysml2/model/version-mark/cli/context.sysml @@ -1,16 +1,14 @@ package VersionMark { - package Cli { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def Context { - metadata info : SoftwareInfo { - description = "Command-line argument and output container (console, error, log file)."; - sourceFiles = ("src/DemaConsulting.VersionMark/Cli/Context.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs"); - designFiles = ("docs/design/version-mark/cli/context.md"); - verificationFiles = ("docs/verification/version-mark/cli/context.md"); - requirementFiles = ("docs/reqstream/version-mark/cli/context.yaml"); - } + part def Context { + metadata info : SoftwareInfo { + description = "Command-line argument and output container (console, error, log file)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Cli/Context.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs"); + designFiles = ("docs/design/version-mark/cli/context.md"); + verificationFiles = ("docs/verification/version-mark/cli/context.md"); + requirementFiles = ("docs/reqstream/version-mark/cli/context.yaml"); } } } diff --git a/docs/sysml2/model/version-mark/cli/program.sysml b/docs/sysml2/model/version-mark/cli/program.sysml index 2b2af3c..6549a7a 100644 --- a/docs/sysml2/model/version-mark/cli/program.sysml +++ b/docs/sysml2/model/version-mark/cli/program.sysml @@ -1,16 +1,22 @@ package VersionMark { - package Cli { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def Program { - metadata info : SoftwareInfo { - description = "Entry point and mode dispatcher (capture, publish, lint, validate)."; - sourceFiles = ("src/DemaConsulting.VersionMark/Program.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/ProgramTests.cs"); - designFiles = ("docs/design/version-mark/cli/program.md"); - verificationFiles = ("docs/verification/version-mark/cli/program.md"); - requirementFiles = ("docs/reqstream/version-mark/cli/program.yaml"); - } + part def Program { + metadata info : SoftwareInfo { + description = "Entry point and mode dispatcher (capture, publish, lint, validate)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Program.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/ProgramTests.cs"); + designFiles = ("docs/design/version-mark/cli/program.md"); + verificationFiles = ("docs/verification/version-mark/cli/program.md"); + requirementFiles = ("docs/reqstream/version-mark/cli/program.yaml"); } } + + // Program dispatches each operational mode to the unit that implements it. + dependency Program to Context; + dependency Program to VersionMarkConfig; + dependency Program to VersionInfo; + dependency Program to MarkdownFormatter; + dependency Program to GlobMatcher; + dependency Program to Validation; } diff --git a/docs/sysml2/model/version-mark/configuration.sysml b/docs/sysml2/model/version-mark/configuration.sysml index a2faed8..b79910e 100644 --- a/docs/sysml2/model/version-mark/configuration.sysml +++ b/docs/sysml2/model/version-mark/configuration.sysml @@ -1,19 +1,17 @@ package VersionMark { - package Configuration { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def ConfigurationSubsystem { - metadata info : SoftwareInfo { - description = "YAML configuration loading, validation, and version capture execution."; - testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/ConfigurationTests.cs"); - designFiles = ("docs/design/version-mark/configuration.md"); - verificationFiles = ("docs/verification/version-mark/configuration.md"); - requirementFiles = ("docs/reqstream/version-mark/configuration.yaml"); - } - - part versionMarkConfig : VersionMarkConfig; - part toolConfig : ToolConfig; - part lintIssue : LintIssue; + part def ConfigurationSubsystem { + metadata info : SoftwareInfo { + description = "YAML configuration loading, validation, and version capture execution."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/ConfigurationTests.cs"); + designFiles = ("docs/design/version-mark/configuration.md"); + verificationFiles = ("docs/verification/version-mark/configuration.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration.yaml"); } + + part versionMarkConfig : VersionMarkConfig; + part toolConfig : ToolConfig; + part lintIssue : LintIssue; } } diff --git a/docs/sysml2/model/version-mark/configuration/lint-issue.sysml b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml index faa34f9..d4283b0 100644 --- a/docs/sysml2/model/version-mark/configuration/lint-issue.sysml +++ b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml @@ -1,16 +1,30 @@ package VersionMark { - package Configuration { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + private import ScalarValues::Integer; + private import ScalarValues::String; - part def LintIssue { - metadata info : SoftwareInfo { - description = "Represents a single configuration validation issue with source location."; - sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/LintIssue.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/LintIssueTests.cs"); - designFiles = ("docs/design/version-mark/configuration/lint-issue.md"); - verificationFiles = ("docs/verification/version-mark/configuration/lint-issue.md"); - requirementFiles = ("docs/reqstream/version-mark/configuration/lint-issue.yaml"); - } + enum def LintSeverity { + enum warning; + enum error; + } + + part def LintIssue { + metadata info : SoftwareInfo { + description = "Represents a single configuration validation issue with source location."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/LintIssue.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/LintIssueTests.cs"); + designFiles = ("docs/design/version-mark/configuration/lint-issue.md"); + verificationFiles = ("docs/verification/version-mark/configuration/lint-issue.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration/lint-issue.yaml"); } + + attribute filePath : String; + attribute line : Integer; + attribute column : Integer; + attribute severity : LintSeverity; + attribute description : String; } + + // ReportIssues writes discovered issues to the Cli Context. + dependency LintIssue to Context; } diff --git a/docs/sysml2/model/version-mark/configuration/tool-config.sysml b/docs/sysml2/model/version-mark/configuration/tool-config.sysml index e8c68db..043225b 100644 --- a/docs/sysml2/model/version-mark/configuration/tool-config.sysml +++ b/docs/sysml2/model/version-mark/configuration/tool-config.sysml @@ -1,16 +1,27 @@ package VersionMark { - package Configuration { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + private import ScalarValues::String; - part def ToolConfig { - metadata info : SoftwareInfo { - description = "Per-tool capture configuration (command, regex, OS-specific overrides)."; - sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs"); - designFiles = ("docs/design/version-mark/configuration/tool-config.md"); - verificationFiles = ("docs/verification/version-mark/configuration/tool-config.md"); - requirementFiles = ("docs/reqstream/version-mark/configuration/tool-config.yaml"); - } + part def ToolConfig { + metadata info : SoftwareInfo { + description = "Per-tool capture configuration (command, regex, OS-specific overrides)."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs"); + designFiles = ("docs/design/version-mark/configuration/tool-config.md"); + verificationFiles = ("docs/verification/version-mark/configuration/tool-config.md"); + requirementFiles = ("docs/reqstream/version-mark/configuration/tool-config.yaml"); } + + // Command dictionary, keyed by OS name ("" for default, "win", "linux", "macos"), + // split into parallel key/value lists since a native map attribute is not + // representable here. + attribute command_key : String [0..*]; + attribute command_value : String [0..*]; + + // Regex dictionary, keyed by OS name ("" for default, "win", "linux", "macos"), + // split into parallel key/value lists since a native map attribute is not + // representable here. + attribute regex_key : String [0..*]; + attribute regex_value : String [0..*]; } } diff --git a/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml index 75b7293..2ff953c 100644 --- a/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml +++ b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml @@ -1,22 +1,31 @@ package VersionMark { - package Configuration { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + import OtsDependencies::*; - part def VersionMarkConfig { - metadata info : SoftwareInfo { - description = "Loads, validates, and executes `.versionmark.yaml` tool version capture."; - sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); - testFiles = ( - "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs", - "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigLoadTests.cs" - ); - designFiles = ("docs/design/version-mark/configuration/version-mark-config.md"); - verificationFiles = ("docs/verification/version-mark/configuration/version-mark-config.md"); - requirementFiles = ( - "docs/reqstream/version-mark/configuration/version-mark-config.yaml", - "docs/reqstream/version-mark/configuration/load.yaml" - ); - } + part def VersionMarkConfig { + metadata info : SoftwareInfo { + description = "Loads, validates, and executes `.versionmark.yaml` tool version capture."; + sourceFiles = ("src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs"); + testFiles = ( + "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs", + "test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigLoadTests.cs" + ); + designFiles = ("docs/design/version-mark/configuration/version-mark-config.md"); + verificationFiles = ("docs/verification/version-mark/configuration/version-mark-config.md"); + requirementFiles = ( + "docs/reqstream/version-mark/configuration/version-mark-config.yaml", + "docs/reqstream/version-mark/configuration/load.yaml" + ); } + + // Tools is keyed by tool name; the key/value pairing is not representable here, + // so this is a flat multiplicity of ToolConfig parts. + part tools : ToolConfig [0..*]; } + + // Load validates and produces LintIssue/ToolConfig records; FindVersions returns VersionInfo. + dependency VersionMarkConfig to ToolConfig; + dependency VersionMarkConfig to LintIssue; + dependency VersionMarkConfig to VersionInfo; + dependency VersionMarkConfig to YamlDotNet; } diff --git a/docs/sysml2/model/version-mark/publishing.sysml b/docs/sysml2/model/version-mark/publishing.sysml index e17a184..efee10b 100644 --- a/docs/sysml2/model/version-mark/publishing.sysml +++ b/docs/sysml2/model/version-mark/publishing.sysml @@ -1,17 +1,15 @@ package VersionMark { - package Publishing { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def PublishingSubsystem { - metadata info : SoftwareInfo { - description = "Markdown report generation from captured version data."; - testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/PublishingTests.cs"); - designFiles = ("docs/design/version-mark/publishing.md"); - verificationFiles = ("docs/verification/version-mark/publishing.md"); - requirementFiles = ("docs/reqstream/version-mark/publishing.yaml"); - } - - part markdownFormatter : MarkdownFormatter; + part def PublishingSubsystem { + metadata info : SoftwareInfo { + description = "Markdown report generation from captured version data."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/PublishingTests.cs"); + designFiles = ("docs/design/version-mark/publishing.md"); + verificationFiles = ("docs/verification/version-mark/publishing.md"); + requirementFiles = ("docs/reqstream/version-mark/publishing.yaml"); } + + part markdownFormatter : MarkdownFormatter; } } diff --git a/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml index d0af269..b346f37 100644 --- a/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml +++ b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml @@ -1,16 +1,17 @@ package VersionMark { - package Publishing { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def MarkdownFormatter { - metadata info : SoftwareInfo { - description = "Converts loaded version records into a consolidated markdown report."; - sourceFiles = ("src/DemaConsulting.VersionMark/Publishing/MarkdownFormatter.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/MarkdownFormatterTests.cs"); - designFiles = ("docs/design/version-mark/publishing/markdown-formatter.md"); - verificationFiles = ("docs/verification/version-mark/publishing/markdown-formatter.md"); - requirementFiles = ("docs/reqstream/version-mark/publishing/markdown-formatter.yaml"); - } + part def MarkdownFormatter { + metadata info : SoftwareInfo { + description = "Converts loaded version records into a consolidated markdown report."; + sourceFiles = ("src/DemaConsulting.VersionMark/Publishing/MarkdownFormatter.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Publishing/MarkdownFormatterTests.cs"); + designFiles = ("docs/design/version-mark/publishing/markdown-formatter.md"); + verificationFiles = ("docs/verification/version-mark/publishing/markdown-formatter.md"); + requirementFiles = ("docs/reqstream/version-mark/publishing/markdown-formatter.yaml"); } } + + // Format takes the loaded VersionInfo records as its input data model. + dependency MarkdownFormatter to VersionInfo; } diff --git a/docs/sysml2/model/version-mark/self-test.sysml b/docs/sysml2/model/version-mark/self-test.sysml index cbaa04e..e6e510a 100644 --- a/docs/sysml2/model/version-mark/self-test.sysml +++ b/docs/sysml2/model/version-mark/self-test.sysml @@ -1,17 +1,15 @@ package VersionMark { - package SelfTest { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def SelfTestSubsystem { - metadata info : SoftwareInfo { - description = "Built-in self-verification of all operational modes."; - testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); - designFiles = ("docs/design/version-mark/self-test.md"); - verificationFiles = ("docs/verification/version-mark/self-test.md"); - requirementFiles = ("docs/reqstream/version-mark/self-test.yaml"); - } - - part validation : Validation; + part def SelfTestSubsystem { + metadata info : SoftwareInfo { + description = "Built-in self-verification of all operational modes."; + testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); + designFiles = ("docs/design/version-mark/self-test.md"); + verificationFiles = ("docs/verification/version-mark/self-test.md"); + requirementFiles = ("docs/reqstream/version-mark/self-test.yaml"); } + + part validation : Validation; } } diff --git a/docs/sysml2/model/version-mark/self-test/validation.sysml b/docs/sysml2/model/version-mark/self-test/validation.sysml index 58dc46a..ca1e9a8 100644 --- a/docs/sysml2/model/version-mark/self-test/validation.sysml +++ b/docs/sysml2/model/version-mark/self-test/validation.sysml @@ -1,16 +1,23 @@ package VersionMark { - package SelfTest { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + import OtsDependencies::*; - part def Validation { - metadata info : SoftwareInfo { - description = "Exercises capture, publish, and lint modes end-to-end for self-validation."; - sourceFiles = ("src/DemaConsulting.VersionMark/SelfTest/Validation.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); - designFiles = ("docs/design/version-mark/self-test/validation.md"); - verificationFiles = ("docs/verification/version-mark/self-test/validation.md"); - requirementFiles = ("docs/reqstream/version-mark/self-test/validation.yaml"); - } + part def Validation { + metadata info : SoftwareInfo { + description = "Exercises capture, publish, and lint modes end-to-end for self-validation."; + sourceFiles = ("src/DemaConsulting.VersionMark/SelfTest/Validation.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs"); + designFiles = ("docs/design/version-mark/self-test/validation.md"); + verificationFiles = ("docs/verification/version-mark/self-test/validation.md"); + requirementFiles = ("docs/reqstream/version-mark/self-test/validation.yaml"); } } + + // Validation drives each functional test re-entrantly through Program, and records + // results via TestResults. + dependency Validation to Context; + dependency Validation to Program; + dependency Validation to VersionInfo; + dependency Validation to PathHelpers; + dependency Validation to TestResults; } diff --git a/docs/sysml2/model/version-mark/utilities.sysml b/docs/sysml2/model/version-mark/utilities.sysml index ddac813..2d8479b 100644 --- a/docs/sysml2/model/version-mark/utilities.sysml +++ b/docs/sysml2/model/version-mark/utilities.sysml @@ -1,17 +1,15 @@ package VersionMark { - package Utilities { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def UtilitiesSubsystem { - metadata info : SoftwareInfo { - description = "Glob-pattern matching and safe path combination helpers."; - designFiles = ("docs/design/version-mark/utilities.md"); - verificationFiles = ("docs/verification/version-mark/utilities.md"); - requirementFiles = ("docs/reqstream/version-mark/utilities.yaml"); - } - - part globMatcher : GlobMatcher; - part pathHelpers : PathHelpers; + part def UtilitiesSubsystem { + metadata info : SoftwareInfo { + description = "Glob-pattern matching and safe path combination helpers."; + designFiles = ("docs/design/version-mark/utilities.md"); + verificationFiles = ("docs/verification/version-mark/utilities.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities.yaml"); } + + part globMatcher : GlobMatcher; + part pathHelpers : PathHelpers; } } diff --git a/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml index 28f8996..64b7b56 100644 --- a/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml +++ b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml @@ -1,16 +1,18 @@ package VersionMark { - package Utilities { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; + import OtsDependencies::*; - part def GlobMatcher { - metadata info : SoftwareInfo { - description = "Resolves glob patterns into concrete file path lists for publish mode."; - sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/GlobMatcher.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/GlobMatcherTests.cs"); - designFiles = ("docs/design/version-mark/utilities/glob-matcher.md"); - verificationFiles = ("docs/verification/version-mark/utilities/glob-matcher.md"); - requirementFiles = ("docs/reqstream/version-mark/utilities/glob-matcher.yaml"); - } + part def GlobMatcher { + metadata info : SoftwareInfo { + description = "Resolves glob patterns into concrete file path lists for publish mode."; + sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/GlobMatcher.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/GlobMatcherTests.cs"); + designFiles = ("docs/design/version-mark/utilities/glob-matcher.md"); + verificationFiles = ("docs/verification/version-mark/utilities/glob-matcher.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities/glob-matcher.yaml"); } } + + // FindMatchingFiles delegates pattern evaluation to Microsoft.Extensions.FileSystemGlobbing. + dependency GlobMatcher to FileSystemGlobbing; } diff --git a/docs/sysml2/model/version-mark/utilities/path-helpers.sysml b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml index 91290b7..e1805fb 100644 --- a/docs/sysml2/model/version-mark/utilities/path-helpers.sysml +++ b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml @@ -1,16 +1,14 @@ package VersionMark { - package Utilities { - private import SoftwareItemMetadata::*; + private import SoftwareItemMetadata::*; - part def PathHelpers { - metadata info : SoftwareInfo { - description = "Safe path combination helpers used to construct paths within temp directories."; - sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/PathHelpers.cs"); - testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/PathHelpersTests.cs"); - designFiles = ("docs/design/version-mark/utilities/path-helpers.md"); - verificationFiles = ("docs/verification/version-mark/utilities/path-helpers.md"); - requirementFiles = ("docs/reqstream/version-mark/utilities/path-helpers.yaml"); - } + part def PathHelpers { + metadata info : SoftwareInfo { + description = "Safe path combination helpers used to construct paths within temp directories."; + sourceFiles = ("src/DemaConsulting.VersionMark/Utilities/PathHelpers.cs"); + testFiles = ("test/DemaConsulting.VersionMark.Tests/Utilities/PathHelpersTests.cs"); + designFiles = ("docs/design/version-mark/utilities/path-helpers.md"); + verificationFiles = ("docs/verification/version-mark/utilities/path-helpers.md"); + requirementFiles = ("docs/reqstream/version-mark/utilities/path-helpers.yaml"); } } } diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml index dfc0900..123c517 100644 --- a/docs/sysml2/views/design-views.sysml +++ b/docs/sysml2/views/design-views.sysml @@ -4,45 +4,52 @@ // inside a named 'view' usage (not a 'view def' definition), and it - not // 'render' - is what scopes the rendered diagram content. package VersionMark { - // Each subsystem now lives in its own VersionMark:: nested package (see - // docs/sysml2/model/version-mark/*.sysml), so the per-subsystem views below need an - // explicit import per subsystem to reference each subsystem part def by simple name. - import VersionMark::Cli::*; - import VersionMark::Configuration::*; - import VersionMark::Capture::*; - import VersionMark::Publishing::*; - import VersionMark::SelfTest::*; - import VersionMark::Utilities::*; + import OtsDependencies::*; view SoftwareStructureView { expose VersionMark::**; + render asInterconnectionDiagram; } - view VersionMarkView { + view VersionMarkSystemView { expose VersionMarkSystem; + expose VersionMarkSystem::*; + render asInterconnectionDiagram; } view CliView { expose CliSubsystem; + expose CliSubsystem::*; + render asInterconnectionDiagram; } view ConfigurationView { expose ConfigurationSubsystem; + expose ConfigurationSubsystem::*; + render asInterconnectionDiagram; } view CaptureView { expose CaptureSubsystem; + expose CaptureSubsystem::*; + render asInterconnectionDiagram; } view PublishingView { expose PublishingSubsystem; + expose PublishingSubsystem::*; + render asInterconnectionDiagram; } view SelfTestView { expose SelfTestSubsystem; + expose SelfTestSubsystem::*; + render asInterconnectionDiagram; } view UtilitiesView { expose UtilitiesSubsystem; + expose UtilitiesSubsystem::*; + render asInterconnectionDiagram; } } From 6c390e8accf1840b6af00fe736ecd311b3db7238 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sun, 19 Jul 2026 16:33:55 -0400 Subject: [PATCH 3/3] Bump pinned sysml2tools tool from beta.12 to beta.13 Required for 'query describe' to surface metadata annotation attribute values (fixed upstream in SysML2Tools beta.13). VersionMark's model already uses 'metadata info : SoftwareInfo { ... }' blocks throughout - this was previously silently invisible to 'query describe' (empty Entries/Summary) because the tool only read comment-based annotations. Verified: sysml2tools query describe --element VersionMark::Program docs/sysml2/**/*.sysml now correctly surfaces 'Metadata SoftwareInfo.sourceFiles: (...)' etc. lines. Full build.ps1 (244x3 TFMs) and lint.ps1 both pass clean after the bump. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index c22086a..a03716c 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -63,7 +63,7 @@ ] }, "demaconsulting.sysml2tools.tool": { - "version": "0.1.0-beta.12", + "version": "0.1.0-beta.13", "commands": [ "sysml2tools" ]