Promote Query Engine to Core as Public API and Update Documentation#49
Merged
Conversation
Moves the `query` CLI command's implementation from the internal `DemaConsulting.SysML2Tools.Tool` project into the public `DemaConsulting.SysML2Tools.Core` library, so it can be called in-process by other applications (e.g. the SysML2Workbench Avalonia app) without shelling out to the CLI. The Tool project becomes a thin adapter over the new public Core API; CLI observable behavior is unchanged except for one new addition. Moved to Core (namespace DemaConsulting.SysML2Tools.Query, all public): - QueryEngine: the 12 verb implementations, plus a new Execute(...) dispatcher that centralizes verb-selection logic for reuse by both the CLI and future library callers. - QueryResult / QueryResultEntry / QueryEntryDirection: plain JSON-serializable result model. - QueryResultRenderer: Markdown/JSON rendering, now public. - QueryResultSerializerContext: source-generated JSON serialization. - QueryVerb / QueryVerbParsing: the 12-verb vocabulary and parsing. - QueryOptions: the shared option record, with the CLI-only `Files` glob-pattern property dropped (library callers pass an already-loaded SysmlWorkspace). - QueryArgumentParser: token parsing, adjusted to return files alongside options since Files no longer lives on QueryOptions. - QualifiedNameShortener: moved from Tool/Utilities to Core/Utilities. New in Core: - QueryResultExporter: WriteMarkdown/WriteJson and async variants that render a QueryResult and write it to a file, for callers (CLI or library) that want file output instead of an in-memory string. Exceptions propagate to the caller since Core has no CLI context to report through. Tool changes (thin adapter): - QueryCommand now calls the public Core QueryEngine/QueryResultRenderer APIs instead of hosting the logic itself. - New QueryCliArgumentParser wraps Core's QueryArgumentParser to also track the CLI-only Files/Output values. - New `--output <file>` flag on the `query` command, mirroring `export`'s `--output` semantics exactly (single output file, not a directory like `render`). When supplied, output is written via QueryResultExporter instead of stdout. Broadened exception handling covers ArgumentException/PathTooLongException for malformed paths. - Context.cs gained a QueryOutput property to carry the new flag. Tests: - Pure QueryEngine/QueryResultRenderer/QueryResultExporter tests moved to a new test/DemaConsulting.SysML2Tools.Tests/Query/ folder in the Core test project; QualifiedNameShortenerTests moved alongside it. - CLI-specific tests (arg parsing, validation errors, stdout formatting, the new --output end-to-end file-writing test) remain in Tool.Tests. - Added ContextTests coverage for the new QueryOutput property. Documentation: - New docs/design, docs/verification, and docs/reqstream entries for the Core Query subsystem, mirroring sibling Core subsystem docs. - Updated docs/design/introduction.md decomposition tree, the Tool query docs (thin-adapter description + --output flag), and the Tool Cli/Context companion docs/tests for the new QueryOutput property. Verified: build.ps1 (0 warnings/errors, full test suite green across net8.0/net9.0/net10.0), fix.ps1, lint.ps1 all clean; manually confirmed `--output` produces byte-identical content to stdout for both Markdown and JSON formats. Ran formal-review sub-agents across all 25 review-sets affected by this change's file list (computed via wcmatch GLOBSTAR|NEGATE|BRACE matching against .reviewmark.yaml); fixed every finding genuinely caused by this change (missing Query entry in the design decomposition tree, missing Core Query verb verification scenarios, wrong heading depth in the Tool query docs, narrow --output exception handling, missing QueryOutput requirement/design/test coverage) and re-verified each fix with a fresh review. Remaining FAILED review-sets were confirmed via `git diff main` to reference files untouched by this branch (pre-existing, unrelated issues such as Template-* placeholder requirement IDs, OTS rendering dependency documentation gaps, and a pre-existing QueryTestFixtures.cs temp-file leak) and were left deferred per instructions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
QualifiedNameShortener physically moved from Tool/Utilities to Core/Utilities as part of the public Query API refactor, but its decomposition-tree entry and legacy per-unit docs/reqstream/review-set were never updated to match: - docs/design/introduction.md: moved the unit's decomposition-tree bullet from Tool's Utilities subsystem to Core's Query subsystem; added Core's Utilities/ folder to the source-tree map. - docs/design/sysml2-tools-tool/utilities.md and docs/verification/sysml2-tools-tool/utilities.md: now describe PathHelpers as the subsystem's sole remaining unit, with a pointer to the new Core location. - Deleted the orphaned Tool-side per-unit docs (design/verification/reqstream) for QualifiedNameShortener; moved their 9 QualifiedNameShortenerTests.cs test-scenario write-ups into docs/verification/sysml2-tools-core/query.md. - docs/reqstream/sysml2-tools-tool/utilities.yaml: dropped the duplicate QualifiedNameShortening requirement; requirements.yaml: removed the now-deleted file's include. - docs/reqstream/sysml2-tools-core/query.yaml: added a new SysML2Tools-Core-Query-QualifiedNameShortening requirement tracing the 9 unit-level tests (previously untracked after the old Tool-side requirements were removed). - .reviewmark.yaml: removed the stale SysML2Tools-Tool-Utilities-QualifiedNameShortener review-set (now redundant with SysML2Tools-Core-Query, which already covers the unit's new location). Verified: build.ps1 (367 + 551x3 tests) and lint.ps1 both green. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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 expands the documentation and review structure to cover the new Query subsystem in the SysML2Tools Core library. It adds detailed design and data-flow documentation for the Query subsystem, updates the architecture diagrams and dependencies, and introduces new review definitions for Query design, verification, and implementation. Additionally, it removes outdated review definitions and clarifies file path inclusions for the Tool's Query subsystem.
Documentation and Architecture Updates:
QueryEngine,QueryResultRenderer,QueryResultExporter). [1] [2] [3] [4]QualifiedNameShorteneras a shared utility. [1] [2] [3]Review Definitions:
QualifiedNameShortenerunder the Tool project, since it is now covered as part of the Core Query subsystem.Other Improvements:
--outputoption for the Query command.