Skip to content

Refactor roadmap and enhance query command with CLI improvements - #13

Merged
Malcolmnixon merged 15 commits into
mainfrom
feature/query-command
Jul 3, 2026
Merged

Refactor roadmap and enhance query command with CLI improvements#13
Malcolmnixon merged 15 commits into
mainfrom
feature/query-command

Conversation

@Malcolmnixon

@Malcolmnixon Malcolmnixon commented Jul 3, 2026

Copy link
Copy Markdown
Member

This pull request introduces support for the new query and help commands, expands the review and documentation coverage for resource (.resx) files and several new subsystems, and updates the semantic model to include new units for resolved references and annotations. It also updates the documentation to reflect these new features, clarifies the review scope for resource files, and provides detailed user guidance for the new commands.

Major feature and documentation additions:

  • Added query and help commands to the CLI, with extensive documentation, usage examples, and option tables in README.md. The query command supports multiple verbs for model analysis, and the help command provides command- and verb-specific help output. [1] [2] [3] [4]
  • Updated the semantic subsystem design to introduce SysmlEdge, SemanticIndex, and SysmlAnnotation units, and revised the data flow to include a reverse-lookup index over resolved references and captured documentation. [1] [2] [3] [4] [5] [6] [7] [8]
  • Updated the review configuration in .reviewmark.yaml to:
    • Explicitly include all .resx files in review scope, with rationale.
    • Add new resource files, subsystems, and test files to the appropriate review groups, including for the Help, Query, Lint, and Render subsystems. [1] [2] [3] [4] [5]
  • Added "resx" and "Resx" to the spelling dictionary in .cspell.yaml to prevent false positives.

Summary of most important changes:

1. CLI Features and User Documentation

  • Introduced the query and help commands, with comprehensive documentation, usage examples, and option tables in README.md. [1] [2] [3] [4]
  • Documented the new subsystems and their relationships in the design docs, including the addition of the Help subsystem and its command dispatch logic. [1] [2]

2. Semantic Model and Internal API

  • Added SysmlEdge, SemanticIndex, and SysmlAnnotation units to the semantic subsystem, updated the data model to expose resolved references and captured documentation, and revised the loading and resolution pipeline accordingly. [1] [2] [3] [4] [5] [6] [7]

3. Review Configuration and Scope

  • Explicitly included .resx files in the review scope, with rationale, and added new resource and implementation files to the appropriate review groups for Help, Query, Lint, and Render subsystems. [1] [2] [3] [4] [5] [6]

4. Spelling Dictionary

  • Added "resx" and "Resx" to the spelling dictionary in .cspell.yaml.

Malcolm Nixon and others added 15 commits July 2, 2026 21:13
Malcolm Nixon Malcolm Nixon
docs: refocus roadmap on remaining 0.1.0 phases and 0.2.0 AI analysis
2a6c106 
Remove completed foundation and the superseded/complete Layout Engine v2
phases (14a/b/c) from the roadmap so it stays forward-looking; that history
lives in the git log and generated release notes. Renumber sections
accordingly.

Add the 0.2.0 'AI-Assisted Model Analysis' direction:
- Phase 20: per-verb CLI command model (each verb owns a typed options
  record) to replace the single flat Context/ArgumentParser.
- Phase 21: query command (uses/used-by/impact/describe/hierarchy/
  requirements/interface/connections/states/list/find) with markdown|json
  output, stable qualified-name IDs, and reverse/relationship indexes.
- Phase 22: dynamic (ad-hoc) views rendered from the CLI without editing
  the SysML model, generalizing the existing --auto synthesis path.
- Phase 23: additional AI-analysis options (SARIF lint, export verb,
  metrics, workspace diff, uniform JSON output).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
docs: strip reference material from roadmap, keep it action-focused
29adf3b 
A roadmap should list work to be done, not embed reference material. Remove
the SysML v2 graphical-notation reference (including the external OMG
repo image tables), the Layout Engine Architecture reference, and the
LayoutTree Vocabulary reference; these describe the tool rather than
planned work and belong in docs/. Renumber sections and update all internal
cross-references; conformance phases now cite 'the SysML v2 graphical
notation (in docs/)' instead of an embedded table.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
docs: drop release-version framing and global phase-gate section
078c895 
Roadmap should list work plus notes on doing it, not predict release
timing or carry a standalone process section. Remove all 0.1.0/0.2.0
release-milestone framing and the 'Definition of Done for a release'
section; regroup items by theme (notation & view conformance; release &
packaging; model query & analysis). Remove the global 'phase gate' section;
per-item completion criteria remain as each item's own Scope/Visual
gate/Gate notes, which is where implementing notes belong.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
feat(language): resolve and index supertype/typing/import edges
b463c44 
Persist resolved qualified-name references that ReferenceResolver
previously computed but discarded, and extend the same resolution
logic to FeatureTyping and ImportedNames references which were
previously never validated or resolved.

- ReferenceResolver.TryResolve now returns the resolved target
  qualified name via an out parameter alongside the existing bool
  success result.
- ReferenceResolver.ResolveNode resolves SupertypeNames,
  FeatureTyping, and ImportedNames uniformly, attaching the
  resulting SysmlEdge list to each node's new ResolvedEdges
  property. Unresolved references continue to use the existing
  diagnostic mechanism and simply produce no edge.
- AstBuilder.VisitImportRule now populates the inherited
  ImportedNames property for both wildcard and named imports.
- Added SysmlEdge (record) and SysmlEdgeKind (Supertype, Typing,
  Import) to represent a resolved reference.
- Added SemanticIndex, a reusable reverse-index over resolved edges
  exposing GetOutgoingEdges, GetIncomingEdges, and AllEdges, intended
  for direct consumption by the forthcoming query command's
  uses/used-by/impact/hierarchy verbs.
- ReferenceResolver.ResolveAll now returns the built SemanticIndex
  instead of void, and WorkspaceLoader wires it into the new
  SysmlWorkspace.Index property.
- Added unit tests covering supertype/typing/import resolution,
  resolution across enclosing namespace scopes, resolution via
  wildcard and named imports, graceful handling of unresolved
  references, and reverse-index incoming/outgoing edge queries
  across a multi-kind fixture model.
- Updated design/verification docs and the reqstream requirement
  set to describe SysmlEdge and SemanticIndex, and appended the
  new/changed source files to the .reviewmark.yaml review-set path
  list.

This is purely additive to the in-memory semantic model; no
external CLI or render behavior changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Capture comment/documentation annotations in AST (doc-comment-capture)
7a33810 
Adds SysmlAnnotation/SysmlAnnotationKind types and a SysmlNode.Annotations property to capture raw comment and documentation text from ownedAnnotation/annotatingElement grammar constructs that were previously parsed but silently dropped by the AST builder. Purely additive to the in-memory model; enables the future query command 'describe' verb to surface this text.

Unit 2 of 6 in the query command feature sequence (builds on b463c44).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
feat(language): capture requirement trace edges (satisfy/verify/alloc…
45ecfe0 
…ate)

Adds Satisfy, Verify, and Allocate cases to SysmlEdgeKind and wires new
AstBuilder visitors (VisitSatisfyRequirementUsage, VisitAllocationUsage,
VisitRequirementUsage) plus a narrow recursive verification-member
tree-walk (FindVerificationMembers/CollectVerificationMembers/
ExtractVerifiedRequirementName) to capture requirement satisfy/verify/
allocate relationships that were previously parsed by ANTLR but dropped
by the AST builder.

ReferenceResolver resolves these new references into SysmlEdge entries
via the same reverse-index infrastructure introduced in unit 1
(SemanticIndex), reusing ExtractConnectorEnds for allocation's two ends
via the "allocation" SysmlConnectionNode keyword variant. Unresolvable
references degrade gracefully (no edge, no crash), matching the
existing diagnostic pattern.

Also fixes two latent ReferenceResolver gaps surfaced by OMG fixture
smoke tests: named SysmlFeatureNode is now pushed onto the namespace
stack during resolution (previously only Package/Definition), and
wildcard/explicit import resolution now resolves the imported
namespace name itself via a new ResolveNamespaceName helper.

Purely additive to the in-memory model; no CLI/query verb wiring in
this unit.

Companion updates: docs/reqstream/sysml2-tools-language.yaml,
docs/design/sysml2-tools-language/semantic/internal/{sysml-edge,
sysml-node,ast-builder,reference-resolver}.md,
docs/verification/sysml2-tools-language.md, and stale-summary fixes in
docs/design/introduction.md and .../semantic/internal.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Add feature-chain resolution for connection endpoints and transitions
9c56a80 
Resolve dotted feature chains (e.g. engine.fuelPort) used in
SysmlConnectionNode.EndpointA/EndpointB and SysmlTransitionNode
Source/Target into qualified names, via a second ReferenceResolver
pass run after namespace/typing/supertype resolution completes.

Adds Connect and Transition SysmlEdgeKind values populated only when
both sides of the chain resolve. Lookup is direct-child-first, then
falls back to the feature's typing, walking supertypes (cycle-guarded)
for inherited features. Scope excludes SysmlSatisfyNode/allocation
endpoints and does not resolve through redefined/subsetted features.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
feat(tool): add query command CLI scaffold with per-verb options
b6c752a 
Introduce a dedicated query command shell for the CLI, parsing
sysml2tools query <verb> --element <name> [options] <files...>
into a new QueryOptions/QueryVerb/QueryCommand abstraction, scoped
separately from the existing flat Context/ArgumentParser used by
lint and render (left unchanged in shape and behavior).

Scaffolds all 11 planned query verbs (uses, used-by, impact,
describe, hierarchy, requirements, interface, connections, states,
list, find) with a shared not-yet-implemented stub dispatcher;
verb business logic is intentionally deferred to a following unit.

- Add Query to SysmlCommand and Context parsing for --element/-e,
  --direction, --kind, --name, --include-stdlib, and verb capture
- Add Query/QueryVerb.cs, Query/QueryOptions.cs, Query/QueryCommand.cs
- Wire query dispatch and help text into Program.cs, documenting the
  dual meaning of --format (render: svg/png, query: md/json)
- Add ContextTests and QuerySubsystemTests covering verb parsing,
  required-option validation, unknown verb handling, and stub behavior
- Add design/verification/reqstream docs for the new Query subsystem
  and update Cli/Context companion docs; append .reviewmark.yaml
- Document query command usage in README under Querying (Preview)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Implement query command verbs against enriched semantic model
f3574af 
Replace all 11 stubbed query verb handlers (describe, uses, used-by,
impact, hierarchy, requirements, interface, connections, states, list,
find) with real logic backed by the SemanticIndex/SysmlNode model
enriched in units 1-4 (reverse-index edges, annotations, resolved
feature chains).

- Add QueryEngine implementing all 11 verb algorithms.
- Add shared QueryResult/QueryResultRenderer/QueryResultSerializerContext
  output layer producing deterministic, alphabetically-ordered Markdown
  (default) and source-generated JSON (--format json).
- Fix AstBuilder.VisitStateUsage to collect nested state/transition
  bodies (was silently dropped, affecting the states/connections verbs
  and unit 4's transition model).
- Add docs/reqstream/sysml2-tools-tool/query.yaml to requirements.yaml
  includes (was orphaned from ReqStream traceability since unit 5).
- Add comprehensive integration test suite: inline per-verb fixtures,
  OMG standard-fixture smoke tests, Markdown/JSON format parity tests,
  and error-path tests (element not found, unparseable file, missing
  required options).
- Update Query subsystem design/verification/reqstream docs, user guide,
  and README with real usage examples for each verb.
- Append new Query test references to .reviewmark.yaml.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Refactor CLI argument parsing into per-command scoped parsers
9a998c4 
Replace the flat, shared ArgumentParser switch (which accepted every
flag for lint/render/query in one switch, allowing e.g. lint --auto
to silently succeed even though lint never uses --auto) with dedicated
per-command parsers:

- GlobalArgumentParser parses only global options (--version, --help,
  --silent, --validate, --results, --log, --depth) up front.
- LintArgumentParser, RenderArgumentParser, and QueryArgumentParser
  each parse ONLY their own command's flags, rejecting any foreign
  flag with a clear ArgumentException naming the offending flag and
  command.
- render's --format (svg|png) and query's --format (md|json) are now
  independently typed/validated via RenderCommandOptions.Format and
  QueryOptions.Format instead of a single ambiguous shared property.
- The query verb token is now a required structural part of query's
  grammar, parsed explicitly by QueryArgumentParser rather than
  inferred via a lazy nullable-check fallback in a shared default case.

Context.cs now dispatches to GlobalArgumentParser followed by the
appropriate per-command parser based on the command token, replacing
the old flat ArgumentParser entirely (no dead code left behind).

Updates design docs, verification docs, and reqstream requirements
under docs/design/sysml2-tools-tool, docs/verification/sysml2-tools-tool,
and docs/reqstream/sysml2-tools-tool to describe the new architecture,
and extends .reviewmark.yaml (append-only) to cover the new source
files. Adds/updates tests proving foreign flags are rejected per
command (lint --auto, render --kind, query describe --auto) and that
the query verb is required.

Verified: dotnet build (0 warnings/errors), dotnet test (1,113/1,113
passing across net8.0/net9.0/net10.0), and the full lint.ps1 quality
gate (markdownlint-cli2, cspell, yamllint, dotnet format, reqstream,
versionmark, reviewmark) all pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
feat(tool): add first-class 'help' command with per-command/verb help…
9c4f178 
… text

Add sysml2tools help [command] [verb] as a top-level command alongside the
existing -h/-?/--help global flag, following the git/npm/cargo/kubectl
convention where both '<tool> help <command>' and '<tool> <command> --help'
coexist and converge on the same content.

- Add SysmlCommand.Help and recognize 'help' as a command token in
  GlobalArgumentParser.
- Add Help/HelpOptions.cs, Help/HelpArgumentParser.cs, Help/HelpCommand.cs to
  parse and dispatch 'help [lint|render|query] [verb]'.
- Add LintCommand.PrintHelp and RenderCommand.PrintHelp as the single source
  of truth for command-specific help text, reused by both 'help <command>'
  and '<command> --help'.
- Extract Program.PrintTopLevelHelp and make the --help dispatch
  command-aware so 'lint --help', 'render --help', 'query --help', and
  'query <verb> --help' show command/verb-specific detail instead of the
  generic top-level help.
- 'help query' summarizes all 11 verbs; 'help query <verb>' shows that
  verb's real flags/example via QueryCommand.PrintVerbHelp.
- Unknown command/verb targets produce a graceful error consistent with
  existing Program.cs exception handling, not a crash.
- --silent suppresses help output the same way it suppresses all other
  Context.WriteLine output, for consistency with existing --silent
  semantics (documented via SysML2Tools-Tool-Help-SilentConsistency).

Add extensive test coverage: bare 'help', per-command help, all 11 query
verbs individually, unknown command/verb handling, --silent interaction,
and regression coverage for -h/-?/--help and the new command-aware
<command> --help behavior.

Update reqstream (help.yaml, context.yaml), design and verification docs
for the new Help subsystem, README.md, user guide, and append a new
SysML2Tools-Tool-Help block to .reviewmark.yaml.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Centralize CLI help text into resx resources and enrich query help
076a666 
Move ~100+ hardcoded help-text WriteLine strings from Program.cs,
Lint/LintCommand.cs, Render/RenderCommand.cs, and Query/QueryCommand.cs
into per-command .resx resource files (ProgramStrings, Lint/LintStrings,
Render/RenderStrings, Query/QueryStrings), each backed by a hand-written
ResourceManager accessor class for i18n-ready culture fallback that works
across net8/net9/net10 without requiring VS designer codegen. Future
locales can be added by dropping in Strings.<culture>.resx files with
zero code changes.

Structural help-assembly logic (per-verb branching, flag list loops)
remains in code; only localizable prose moved to resx.

Enrich query command help content:
- Added one concrete example invocation per query verb, using real
  element names from the VehicleExample fixtures.
- Added JSON/Markdown output-shape schema hints per verb, verified
  against the actual QueryResult/QueryResultRenderer shapes.
- Added a "typical workflow" note to the query overview help,
  validated against QueryVerbParsing.RequiresElement behavior.

Added ResxResourceTests.cs proving end-to-end resx/accessor wiring,
updated QuerySubsystemTests for the enriched help content, and updated
reqstream, design, verification, and user guide docs accordingly.
Appended .reviewmark.yaml (resx files added to needs-review scope) and
.cspell.yaml (resx/Resx) append-only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Fix Markdown corruption from multi-line comment/doc annotations in qu…
0ca1fd5 
…ery describe

The describe verb spliced SysmlAnnotation.Text (captured verbatim, including
embedded newlines/tabs/'*' continuation markers from multi-line /* ... */
blocks) directly into a single Summary line. QueryResultRenderer.RenderMarkdown
then emitted each summary entry as a single unescaped bullet, so a multi-line
doc comment spilled across multiple raw lines, breaking the one-fact-per-bullet
Markdown structure an AI agent would rely on when parsing.

Add QueryEngine.NormalizeAnnotationText to collapse annotation text to a
single line (splitting on newlines, trimming whitespace and leading '*'
continuation markers per line, dropping empties, rejoining with spaces)
before it is added as a summary fact. JSON output was already correct
(properly escaped) and is unaffected.

Found by an independent code-review agent pass against the full
feature/query-command branch diff.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Fix stale query-command status in README and user guide scope
3141755 
README still described the query command as a preview with verb logic
'shipping incrementally in future releases', which has been false since all
11 verbs were fully implemented. Updated the feature bullet to reflect the
shipped state and its AI-agent-facing purpose.

The user guide's Purpose/Scope sections only mentioned lint/render, even
though the guide already has full query and help sections in the body.
Updated the introduction to mention all four commands so the front matter
matches the guide's actual content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolm Nixon Malcolm Nixon
Fix reqstream test-name matching for query and annotation requirements
89549e5 
CI's 'Generate Requirements Report, Justifications, and Trace Matrix' step
(dotnet reqstream --enforce) was failing on every push since the
query-verbs-implementation commit: 16 requirements (all 11 query verbs plus
StdlibFilter/ElementNotFound/OutputFormat/AnnotationCapture/
RequirementTraceEdges) were reported as unsatisfied despite their tests
actually passing.

Root cause: docs/reqstream-usage.md documents that 'ReqStream matches tests
by method name in test results' (bare method name, no class qualifier), but
several 'tests:' entries introduced across the query/annotation/requirement-
trace units used a 'ClassName.MethodName' format instead (e.g.
'QueryVerbsTests.Uses_ReportsOutgoingSupertypeTypingImportEdges'). Since the
actual TRX-recorded test name has no such literal 'ClassName.' prefix
segment as an exact match target, reqstream could not match these entries
to any recorded outcome, so they always showed 0 passed / 0 failed
('not found') regardless of the underlying test's real pass/fail status.

Verified locally end-to-end: ran the exact CI sequence (dotnet build
--configuration Release, dotnet test --logger trx --results-directory
artifacts, then dotnet reqstream --tests 'artifacts/**/*.trx' --enforce)
before and after this fix. Before: 218/253 satisfied, all 16 affected IDs
unsatisfied. After: 234/253 satisfied, all 16 affected IDs now satisfied;
the remaining 19 unsatisfied 'Template-*' IDs are the expected local-only
gap (they require cross-platform/OTS-tool TRX artifacts only produced by
the full CI matrix, not a single local Windows run) and are unrelated to
this branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@Malcolmnixon
Malcolmnixon merged commit fb8a782 into main Jul 3, 2026
15 checks passed
@Malcolmnixon
Malcolmnixon deleted the feature/query-command branch July 3, 2026 17:21
This was referenced Jul 27, 2026
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
@dependabot dependabot Bot mentioned this pull request Jul 27, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Malcolmnixon