Refactor packaging to support independent Language and Stdlib NuGet packages - #14
Merged
Merged
Conversation
…package to DemaConsulting.SysML2Tools.Tool - Core.csproj: IsPackable=true, add packaging metadata (readme, icon, tags, NoWarn NU5104 for the pre-release Rendering.Layout dependency), and embed the internal (unpublished) Language/Stdlib assemblies directly into the package via CopyProjectReferencesToPackage instead of listing them as bogus NuGet dependencies. - Tool.csproj: PackageId renamed from DemaConsulting.SysML2Tools to DemaConsulting.SysML2Tools.Tool (ToolCommandName/AssemblyName unchanged). - build.yaml: dotnet pack now writes to a shared ./artifacts/packages folder; Upload packages step and integration-test's dotnet tool install updated accordingly. - README.md, docs/design/introduction.md, docs/user_guide/introduction.md: updated NuGet package tables, install instructions, and badge/link URLs to reflect the two real packages (Core, Tool) instead of stale bare-named/Svg/Png references.
…docs Add DemaConsulting.ApiMark.MSBuild 0.4.9 PackageReference and ApiMarkPackDocs=true to DemaConsulting.SysML2Tools.Core.csproj so the packable Core NuGet package ships generated Markdown API reference documentation (from existing XML doc comments) alongside the assembly. - Verified end-to-end: dotnet build generates src/.../Core/api/ on disk; dotnet pack + nupkg inspection confirms the api/ folder is included inside the .nupkg (PackagePath api/**). - Add **/api/** ignore entries to .gitignore, .markdownlint-cli2.yaml, and .cspell.yaml so the regenerated-on-every-build ApiMark output is never committed or linted, following the existing **/generated/** convention. - Add one-sentence mentions of the bundled generated API docs to README.md and docs/user_guide/introduction.md. - Language.csproj/Stdlib.csproj intentionally untouched: Core's public API surface exposes no Language/Stdlib types, so ApiMark on Core alone is sufficient for baseline generation. build.ps1: 100% green, same test counts as d83030a (275 + 166 tests). fix.ps1 / lint.ps1: clean, no errors or warnings.
… API reference
Wires DemaConsulting.ApiMark.MSBuild into Language.csproj and Stdlib.csproj (both
IsPackable=false) and adds a CopyLanguageAndStdlibApiDocsToPackage target to
Core.csproj that folds their generated api/ folders into Core's own package
api/ folder (excluding each project's own single-assembly api.md index to avoid
collisions), plus extends CopyProjectReferencesToPackage to also embed
Language.xml/Stdlib.xml alongside the DLLs in lib/{tfm}/ for IntelliSense.
Adds internal static NamespaceDoc sentinel classes (ApiMark's supported
namespace-summary convention) with <summary>/<remarks>/<example> content to:
- DemaConsulting.SysML2Tools.Rendering (Core)
- DemaConsulting.SysML2Tools.Semantic (Language)
- DemaConsulting.SysML2Tools.Semantic.Internal (Language)
- DemaConsulting.SysML2Tools.Parser (Language)
- DemaConsulting.SysML2Tools.Stdlib (Stdlib)
Also strengthens XML doc comments/examples on the key entry-point types:
DiagramRenderer.RenderWorkspace, ILayoutStrategy/ViewContext, WorkspaceLoader,
SysmlNode, and StdlibProvider.GetSymbolTable, grounded in real call sites from
RenderCommand.RunAsync and the WorkspaceLoaderTests/StdlibProviderTests/
RenderIntegrationTests test suites.
Updates .reviewmark.yaml to attach each new NamespaceDoc.cs to its subsystem's
existing review-set file lists.
Verified end-to-end with a real dotnet pack of Core: the extracted nupkg's
api/ folder now contains pages for Rendering, Parser, Semantic (with nested
Semantic/Internal), and Stdlib namespaces, and lib/{tfm}/ contains
Language.xml/Stdlib.xml alongside the embedded DLLs for all three TFMs.
…B3026 race - CopyLanguageAndStdlibApiDocsToPackage now carries the same TFM-restriction condition used by ApiMark's own GenerateApiMarkDocumentation and _ApiMarkIncludeDocsInPackage targets, so it runs exactly once per pack/build instead of once per inner per-TFM build. This eliminates the MSB3026 'file is being used by another process' race previously masked only by MSBuild's automatic retry. - Added a RoslynCodeTaskFactory inline task, MergeApiMarkNamespaceIndex, that appends Language's and Stdlib's own namespace-table rows into Core's generated api.md after the copy step. The packed api/api.md index now links to all folded-in namespace pages (Parser, Parser.Antlr, Semantic, Semantic.Internal, Stdlib) in addition to Core's own Rendering namespace, instead of leaving them as orphaned files only reachable by browsing the raw api/ folder tree. - Reworded Parser/NamespaceDoc.cs's <remarks> to distinguish the public WorkspaceParser.ParseSource method from the internal ParseSourceToCst helper, so the prose no longer implies both are equally-accessible API surface. Verified with a real dotnet pack + nupkg extraction (zero MSB3026 warnings, all 6 namespace rows present and linking to existing files), build.ps1 (441 tests x 3 TFMs, all green), fix.ps1, and lint.ps1 (clean).
A dotnet pack of Core revealed its nupkg's api/ folder contained 8,657 ApiMark-generated Markdown files, of which 8,547 (98.7%) were pure ANTLR4-codegen noise: one doc page per generated grammar-rule visitor/listener method on the SysMLv2Lexer/SysMLv2Parser classes under DemaConsulting.SysML2Tools.Language/Parser/Antlr. Nothing outside the Language project references these generated types directly (the real public entry point is WorkspaceParser), so this bloated the nupkg to ~7MB while providing zero value to consumers. The ANTLR-generated .cs files themselves (per docs/design/ots/antlr4.md) must not be edited, so the fix has to happen at the doc-generation/packaging layer. DemaConsulting.ApiMark.MSBuild 0.4.10 adds a native exclusion feature for exactly this: a repeatable `--exclude <wildcard>` CLI option and its MSBuild equivalent, the `ApiMarkExclude` property, forwarded verbatim to ApiMarkTask. This is applied at the Language project's own ApiMark generation step - the true source of the noise - rather than by post-hoc filtering copied files in Core's CopyLanguageAndStdlibApiDocsToPackage target. Excluding at the source means Language's own standalone generated api/ folder never contains the noise in the first place, so nothing downstream (including Core's copy/merge step) needs special-case handling for it. This is far cleaner than a hand-rolled copy-time glob-exclusion or regex-based dangling-link pruning approach, since the wildcard exclude is a first-class supported feature of the tool with verified, correct namespace-index handling (no dangling links left behind). Changes: - Bump DemaConsulting.ApiMark.MSBuild 0.4.9 -> 0.4.10 in Core, Language, and Stdlib csproj files. - Add <ApiMarkExclude>DemaConsulting.SysML2Tools.Parser.Antlr*</ApiMarkExclude> to Language.csproj so its own ApiMark generation excludes the ANTLR namespace at the source. - Core.csproj's CopyLanguageAndStdlibApiDocsToPackage target required no changes: it never contained an ANTLR-specific exclusion glob (its only Exclude= clauses target each project's own api.md index, which is unrelated and unaffected by this fix). Verified via a clean dotnet pack of Core: api/ folder now contains 127 files (down from 8,657), no DemaConsulting.SysML2Tools.Parser.Antlr files/folders present, real Parser namespace docs preserved (DemaConsulting.SysML2Tools.Parser.md, WorkspaceParser.md, WorkspaceParseResult.md, SysmlDiagnostic.md, DiagnosticSeverity.md), no dangling links in api.md, and nupkg size down from ~7MB to ~2.6MB (the api/ folder itself is only ~0.06MB uncompressed; the remaining nupkg size is the embedded lib/ assemblies across 3 target frameworks, unrelated to this fix). Full build.ps1 (build+tests), fix.ps1, and lint.ps1 all pass clean with no production code changes.
…ic.Internal->Semantic.Model rename, examples, ctors - FIX1: document DemaConsulting.Rendering.Svg/.Skia package requirements for renderer examples - FIX2: remove stale 'added in later units' from SemanticIndex + design doc; sweep for similar artifacts - FIX3: clarify SysmlLoadResult.Workspace null semantics, add diagnostic-loop example - FIX4: add GetOutgoingEdges/GetIncomingEdges traversal example to SemanticIndex - FIX5: rewrite SysmlWorkspace.Declarations doc to lead with stdlib+user content fact - FIX6: add 'Inherited from SysmlNode' remarks to 9 concrete node subtypes - FIX7: mark AstSerializer/AstDeserializer as stdlib pre-compilation infrastructure - FIX8: rename namespace/folder Semantic.Internal -> Semantic.Model (pure rename) - FIX9: strengthen stdlib-requirement framing in Semantic namespace doc - FIX10: add explicit documented parameterless constructors to SysmlWorkspace/DiagramRenderer - FIX11: investigate ApiMark file-naming section config (none available; no change) - FIX12: replace xUnit-style example in WorkspaceLoader.LoadAsync with realistic app code
…lder The rename from Semantic/Internal to Semantic/Model was specifically because these types (SysmlNode, SemanticIndex, SymbolTable, etc.) are public API, not internal implementation. The folder-layout description still called them 'internal implementation' after the rename, reintroducing the same contradiction the rename was meant to fix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Workspace param doc now states it is always non-null (matches WorkspaceLoader.LoadAsync and the property's own remarks), instead of the previous incorrect 'or null if loading failed entirely'.
- Annotations remarks now describe only current shipped behavior in present tense, removing sprint-planning language ('deferred to a future unit', 'not yet captured').
Follow-up to clean-room review fixes: the previous retry cycle removed 'deferred to a future unit'/'added in later units' language from XML doc comments (SysmlLoadResult.cs, SysmlNode.cs) but missed the same phrasing duplicated in the corresponding design documentation pages under docs/design/sysml2-tools-language/semantic/internal/. Rewritten to describe current shipped behavior neutrally, consistent with the corrected source doc comments.
…(public API, not internal)
Mirrors the earlier Semantic.Internal -> Semantic.Model C# namespace rename.
The folder groups the public semantic model types (SysmlNode/subtypes, SysmlEdge,
SemanticIndex, SysmlAnnotation, SymbolTable) together with a few internal
build/resolve helpers (AstBuilder, ReferenceResolver, SupertypeWalker) - calling
the whole subsystem 'Internal' was misleading. This rename completes the
migration by renaming the parallel design, verification, and reqstream doc
trees from semantic/internal to semantic/model, fixing subsystem-level heading
and prose ('Semantic Internal Subsystem' -> 'Semantic Model Subsystem'), and
renaming the '-Internal-' requirement ID token to '-Model-' across the affected
reqstream YAML files. Also adds the previously-missing semantic-index.md,
sysml-annotation.md, and sysml-edge.md entries to design/definition.yaml and
verification/definition.yaml input-files lists.
Split the previous 2-package model (Core, Tool) into a 4-package model by making Language and Stdlib independently packable: - DemaConsulting.SysML2Tools.Language and .Stdlib now set IsPackable=true with full package metadata (matching Core/Tool conventions) and their own ApiMark-generated docs bundled into their own nupkg. - Core.csproj no longer bundles Language/Stdlib DLLs via PrivateAssets=all ProjectReferences; it now uses plain ProjectReferences so dotnet pack emits normal <dependency> elements referencing the Language/Stdlib packages (transitive resolution via NuGet), matching standard SDK-style multi-package repo behavior. - Removed the CopyLanguageAndStdlibApiDocsToPackage target, the MergeApiMarkNamespaceIndex inline RoslynCodeTaskFactory task, and all related namespace-index merge/prune logic from Core.csproj -- each package now ships only its own docs, eliminating the doc-merge hack. - Updated README.md and docs/user_guide/introduction.md to describe the 4-package model instead of the previous 2-package/bundled-docs model. This is a packaging-only change; runtime behavior is unchanged (441/441 tests pass). Verified via dotnet build/test/pack: dotnet pack now produces 4 nupkgs (+ 4 snupkgs), Core's nuspec correctly lists <dependency> entries for Language and Stdlib instead of embedding their DLLs, and Language/Stdlib's own api/ doc folders are bundled in their own packages.
From the full-branch code-review: - Fix Core/Rendering/NamespaceDoc.cs example: replace a Workspace-is-null check (which can never trigger, per this branch's own documented always-non-null guarantee) with the correct HasErrors check, matching WorkspaceLoader.LoadAsync's own example. - Fix Stdlib/NamespaceDoc.cs example: replace an xUnit Assert.True call (not valid application code) with realistic WorkspaceLoader.LoadAsync usage, matching the same cleanup already done elsewhere this branch. From parallel formal-review agents (gpt-5.4-mini) against affected .reviewmark.yaml review sets: - docs/design/sysml2-tools-language.md: stop describing the renamed Semantic.Model subtree as 'internal', add the missing public SysmlEdge/SemanticIndex/SysmlAnnotation types to the subsystem inventory and diagram, and correct 'Six concrete subtypes' of SysmlNode to the real nine (add SysmlConnectionNode, SysmlTransitionNode, SysmlSatisfyNode). - docs/design/sysml2-tools-language/semantic/model.md: correct the overview to describe SysmlNode/SysmlEdge/SysmlAnnotation/SemanticIndex as the public model API (not internal), and add the missing SysmlNode entry to the unit inventory table (8 units, not 7). - docs/design/introduction.md: fix a naming inconsistency introduced by the earlier Core packaging rename -- the Software Structure list still named the core system 'DemaConsulting.SysML2Tools' instead of 'DemaConsulting.SysML2Tools.Core', contradicting the NuGet package table added in the same file. - docs/design/sysml2-tools-core.md, docs/design/sysml2-tools-stdlib.md: add a Packaging section documenting the ApiMark/GenerateDocumentationFile wiring and (for Stdlib) independent-package status added by this branch's packaging restructure -- both were previously undocumented. Not fixed (pre-existing, out of scope for this branch, flagged for the maintainer separately): stale 'six node types' wording in ast-serializer.md/ast-deserializer.md verification docs, a missing Error Handling section in ast-deserializer.md design doc, a Theme.Font contract mismatch between sysml2-tools-core.md and rendering.md, a heading-depth issue in stdlib-provider.md, a missing Query subsystem entry in introduction.md, README relative-link-format and render --auto behavior-documentation mismatches, and reqstream coverage gaps for SysmlEdge/SemanticIndex/SysmlAnnotation/SerializedStdlib/ AstSerializerContext -- none of these were introduced or touched by this branch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jul 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request makes significant improvements to documentation structure, CI/CD packaging, and code review configuration to better reflect the current architecture and packaging of the SysML2Tools project. The main changes include renaming and reorganizing subsystems from "Internal" to "Model", updating documentation and review paths to match this, and refining the packaging and publishing process for NuGet and API docs. It also updates the README and workflow files to clarify package boundaries and usage.
Documentation and Source Structure Updates
NamespaceDoc.csfiles and their review paths for enhanced API documentation coverage [1] [2] [3] [4] [5] [6].NuGet Packaging and CI/CD Pipeline Improvements
DemaConsulting.SysML2Tools.Tooland updated the build workflow to output and upload artifacts from theartifacts/packagesdirectory [1] [2] [3] [4] [5] [6].Linting and Spellchecking Configuration
api/directory (containing generated API docs) to the ignore lists for both cspell and markdownlint to prevent unnecessary linting of generated files [1] [2].These changes improve maintainability, clarify the public API surface, and ensure consistency across documentation, CI/CD, and code review processes.