Promote Query Engine to Core as Public API and Update Documentation

.reviewmark.yaml

@@ -533,6 +533,41 @@ reviews:
       - "src/DemaConsulting.SysML2Tools.Core/Io/NamespaceDoc.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Io/GlobFileCollectorTests.cs"
 
+  - id: SysML2Tools-Core-Query-Design
+    title: Review that DemaConsulting.SysML2Tools Query Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/query.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/query.md"
+
+  - id: SysML2Tools-Core-Query-Verification
+    title: Review that DemaConsulting.SysML2Tools Query Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/query.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/query.md"
+
+  - id: SysML2Tools-Core-Query
+    title: Review that DemaConsulting.SysML2Tools Query Implementation is Correct
+    context:
+      - docs/design/sysml2-tools-core.md
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/design/sysml2-tools-core/query.md
+    paths:
+      - "docs/reqstream/sysml2-tools-core/query.yaml"
+      - "docs/design/sysml2-tools-core/query.md"
+      - "docs/verification/sysml2-tools-core/query.md"
+      - "src/DemaConsulting.SysML2Tools.Core/Query/*.cs"
+      - "src/DemaConsulting.SysML2Tools.Core/Utilities/QualifiedNameShortener.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Query/*.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Utilities/QualifiedNameShortenerTests.cs"
+
   - id: SysML2Tools-Core-Filtering-Design
     title: Review that DemaConsulting.SysML2Tools Filtering Design is Consistent and Complete
     context:
@@ -902,20 +937,6 @@ reviews:
       - "src/**/Utilities/PathHelpers.cs"
       - "test/**/Utilities/PathHelpersTests.cs"
 
-  - id: SysML2Tools-Tool-Utilities-QualifiedNameShortener
-    title: Review of SysML2 Tools QualifiedNameShortener unit implementation
-    context:
-      - docs/design/sysml2-tools-tool.md
-      - docs/reqstream/sysml2-tools-tool.yaml
-      - docs/design/sysml2-tools-tool/utilities.md
-      - docs/reqstream/sysml2-tools-tool/utilities.yaml
-    paths:
-      - "docs/reqstream/sysml2-tools-tool/utilities/qualified-name-shortener.yaml"
-      - "docs/design/sysml2-tools-tool/utilities/qualified-name-shortener.md"
-      - "docs/verification/sysml2-tools-tool/utilities/qualified-name-shortener.md"
-      - "src/**/Utilities/QualifiedNameShortener.cs"
-      - "test/**/Utilities/QualifiedNameShortenerTests.cs"
-
   - id: SysML2Tools-Tool-Lint
     title: Review of SysML2 Tools Lint subsystem architecture and interfaces
     context:
@@ -959,14 +980,14 @@ reviews:
       - "docs/reqstream/sysml2-tools-tool/query.yaml"
       - "docs/design/sysml2-tools-tool/query.md"
       - "docs/verification/sysml2-tools-tool/query.md"
-      - "src/DemaConsulting.SysML2Tools.Tool/Query/*.cs"
+      - "src/DemaConsulting.SysML2Tools.Tool/Query/QueryCommand.cs"
+      - "src/DemaConsulting.SysML2Tools.Tool/Query/QueryCliArgumentParser.cs"
+      - "src/DemaConsulting.SysML2Tools.Tool/Query/QueryStrings.cs"
       - "src/DemaConsulting.SysML2Tools.Tool/Query/QueryStrings.resx"
       - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QuerySubsystemTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tool.Tests/Resources/ResxResourceTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QueryTestFixtures.cs"
       - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QueryVerbsTests.cs"
-      - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QueryRenderingTests.cs"
-      - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QueryOmgFixtureTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tool.Tests/Query/QueryErrorPathTests.cs"
 
   - id: SysML2Tools-Tool-Export

README.md

@@ -257,6 +257,7 @@ sysml2tools help [lint|render|query [<query-verb>]|export]
 | `<globs>` | One or more glob patterns for `.sysml` input files |
 | `--element <name>`, `-e <name>` | Qualified name of the target element; required for every verb except `list`/`find` |
 | `--format markdown\|json` | Output format (default: `markdown`); distinct from `render`'s `--format` (`svg`/`png`) |
+| `--output <file>` | Write query report to this **file** (default: stdout); differs from `render`'s `--output` dir |
 | `--walk-depth <#>` | Maximum impact-walk depth (`impact` verb only) |
 | `--direction up\|down\|both` | Traversal direction (`hierarchy` verb only) |
 | `--kind <kind>` | Element-kind filter (`list`/`find` verbs only) |

docs/design/introduction.md

@@ -114,6 +114,27 @@ system, subsystem, and unit levels:
     - **GlobFileCollector** (Unit) — resolves ordered glob patterns (with `!` exclusions,
       recursive `**` matching, and bare-`*` extension filtering) to a sorted, deduplicated
       list of absolute file paths
+  - **Query** (Subsystem) — public, reusable model-analysis API answering 12 fixed questions
+    over an already-loaded semantic workspace and returning a uniform `QueryResult` that
+    callers can render as Markdown or JSON or write to a file
+    - **QueryVerb** (Unit) — fixed 12-verb vocabulary, token conversion, and the
+      `RequiresElement` rule
+    - **QueryOptions** (Unit) — immutable option record shared by every verb
+    - **QueryArgumentParser** (Unit) — parses a token list into `(QueryOptions?, Files)` for
+      callers that accept the same verb/option grammar as the CLI
+    - **QueryEngine** (Unit) — public execution surface: 12 verb methods plus `Execute`,
+      centralizing the verb switch used by both library callers and the CLI adapter
+    - **QueryResult** (Unit) — verb-agnostic result model (`QueryResult`, `QueryResultEntry`,
+      `QueryEntryDirection`)
+    - **QueryResultRenderer** (Unit) — shared Markdown/JSON rendering and deterministic
+      sorting layer
+    - **QueryResultSerializerContext** (Unit) — source-generated `System.Text.Json` context
+      used by `RenderJson`
+    - **QueryResultExporter** (Unit) — synchronous and asynchronous file-writing wrappers
+      around the renderer
+    - **QualifiedNameShortener** (Unit) — strips the longest shared leading `::`-segment
+      prefix across a pool of qualified names, used only by the `dependencies` verb's
+      Markdown rendering
 - **DemaConsulting.SysML2Tools.Tool** (System) — dotnet tool: thin CLI wrapper and
   orchestration
   - **Program** (Unit) — entry point and execution orchestrator
@@ -140,9 +161,6 @@ system, subsystem, and unit levels:
     - **Validation** (Unit) — self-validation test runner
   - **Utilities** (Subsystem) — shared utilities
     - **PathHelpers** (Unit) — safe path combination utilities
-    - **QualifiedNameShortener** (Unit) — strips the longest common leading `::`-segment prefix
-      shared across a pool of qualified names, used by the `query dependencies` verb's Markdown
-      rendering
 
 **OTS Dependencies:**
 
@@ -186,6 +204,10 @@ reviewers an explicit navigation aid from design to code:
     - **Rendering/** — SysML-coupled rendering pipeline (`ILayoutStrategy`, `DiagramRenderer`)
     - **Io/** — shared file glob pattern resolution used by the Tool project's
       lint/render/query commands (`GlobFileCollector`)
+    - **Query/** — public, reusable model-analysis API (`QueryVerb`, `QueryOptions`,
+      `QueryArgumentParser`, `QueryEngine`, `QueryResult`, `QueryResultRenderer`,
+      `QueryResultSerializerContext`, `QueryResultExporter`)
+    - **Utilities/** — shared helper used by the Query subsystem (`QualifiedNameShortener`)
   - **DemaConsulting.SysML2Tools.Tool/** — dotnet tool CLI wrapper
     - **Cli/** — command-line interface subsystem
     - **Lint/** — lint command subsystem

docs/design/sysml2-tools-core.md

@@ -2,23 +2,27 @@
 
 ## Architecture
 
-The `DemaConsulting.SysML2Tools` core library provides the Filtering, Layout, Rendering, and Io
-subsystems for SysML v2 diagram generation and shared file-discovery. It depends on
-`DemaConsulting.SysML2Tools.Language` for parsing and semantic analysis, and on
-`DemaConsulting.SysML2Tools.Stdlib` for the pre-compiled standard library.
-
-The core library provides four subsystems: **Filtering**, **Layout**, **Rendering**, and **Io**.
-The Filtering subsystem parses and evaluates the Phase 1 subset of standalone
-`filter [<expr>];` statements against metadata annotations captured by the semantic model. The Layout
-subsystem maps the SysML semantic model onto the `LayoutTree` intermediate representation — nine
-immutable node record types covering all SysML diagram elements — which is provided off-the-shelf
-by the `DemaConsulting.Rendering` package, and delegates geometric placement and routing to the
-off-the-shelf `DemaConsulting.Rendering.Layout` layered algorithm. The Rendering subsystem
-consumes the off-the-shelf rendering contracts (`IRenderer`, `Theme`, `RenderOptions`,
-`RenderOutput`) from the `DemaConsulting.Rendering.Abstractions` package and retains the
-SysML-coupled `ILayoutStrategy` and `DiagramRenderer` that drive the pipeline. The Io subsystem
-provides `GlobFileCollector`, a shared file glob pattern resolver used by the Tool project's
-`lint`, `render`, and `query` commands; it has no dependency on the SysML semantic model.
+The `DemaConsulting.SysML2Tools` core library provides the Filtering, Layout, Rendering,
+Query, and Io subsystems for SysML v2 diagram generation, model analysis, and shared file-
+discovery. It depends on `DemaConsulting.SysML2Tools.Language` for parsing and semantic
+analysis, and on `DemaConsulting.SysML2Tools.Stdlib` for the pre-compiled standard library.
+
+The core library provides five subsystems: **Filtering**, **Layout**, **Rendering**,
+**Query**, and **Io**. The Filtering subsystem parses and evaluates the Phase 1 subset of
+standalone `filter [<expr>];` statements against metadata annotations captured by the
+semantic model. The Layout subsystem maps the SysML semantic model onto the `LayoutTree`
+intermediate representation — nine immutable node record types covering all SysML diagram
+elements — which is provided off-the-shelf by the `DemaConsulting.Rendering` package, and
+delegates geometric placement and routing to the off-the-shelf
+`DemaConsulting.Rendering.Layout` layered algorithm. The Rendering subsystem consumes the
+off-the-shelf rendering contracts (`IRenderer`, `Theme`, `RenderOptions`, `RenderOutput`)
+from the `DemaConsulting.Rendering.Abstractions` package and retains the SysML-coupled
+`ILayoutStrategy` and `DiagramRenderer` that drive the pipeline. The Query subsystem exposes
+Core's public model-analysis API — `QueryEngine`, `QueryResultRenderer`,
+`QueryResultExporter`, and their shared result model — over an already-loaded
+`SysmlWorkspace`; see `docs/design/sysml2-tools-core/query.md`. The Io subsystem provides
+`GlobFileCollector`, a shared file glob pattern resolver used by the Tool project's `lint`,
+`render`, and `query` commands; it has no dependency on the SysML semantic model.
 
 ```mermaid
 flowchart TD
@@ -41,13 +45,21 @@ flowchart TD
         Theme
         RenderOptions
     end
+    subgraph Query
+        QueryEngine
+        QueryResultRenderer
+        QueryResultExporter
+    end
     subgraph Io
         GlobFileCollector
     end
     Language --> FilterExpressionParser
     Language --> FilterExpressionEvaluator
     Language --> DiagramRenderer
+    Language --> QueryEngine
     Stdlib --> DiagramRenderer
+    QueryEngine --> QueryResultRenderer
+    QueryResultRenderer --> QueryResultExporter
     DiagramRenderer --> FilterExpressionParser
     DiagramRenderer --> FilterExpressionEvaluator
     DiagramRenderer --> ILayoutStrategy
@@ -90,7 +102,8 @@ flowchart TD
 ## Dependencies
 
 - **DemaConsulting.SysML2Tools.Language** — provides `WorkspaceLoader`, `SysmlWorkspace`,
-  `SysmlNode` and all subtypes used by `DiagramRenderer` for pattern-matching view declarations.
+  `SysmlNode` and all subtypes used by `DiagramRenderer` for pattern-matching view declarations,
+  and by `QueryEngine` for public model-analysis queries.
 - **DemaConsulting.SysML2Tools.Stdlib** — provides `StdlibProvider.GetSymbolTable()` used
   by `DiagramRenderer` to seed the semantic workspace with the pre-compiled standard library.
 
@@ -146,9 +159,21 @@ N/A — not a safety-classified software item.
    expose-scoped candidate definitions by reading their directly-owned `SysmlMetadataNode`
    children; when parsing fails, layout falls back to the unfiltered scope with a warning.
 
+### Query Data Flow
+
+1. A library caller supplies an already-loaded `SysmlWorkspace`, `QueryOptions`, and (for
+   element-scoped verbs) a resolved `SysmlNode` to `QueryEngine.Execute` or a verb-specific
+   method.
+2. `QueryEngine` reads the semantic workspace's declarations, reverse index, resolved edges,
+   and child nodes to build a uniform `QueryResult` for the requested verb.
+3. `QueryResultRenderer` sorts the result's entries once and renders Markdown or JSON; the
+   `dependencies` verb's Markdown path additionally shortens shared qualified-name prefixes via
+   `QualifiedNameShortener`.
+4. `QueryResultExporter` optionally persists the rendered output to a caller-chosen file path.
+
 ## Design Constraints
 
 - Platform: multi-targets net8.0, net9.0, and net10.0 on Windows, Linux, and macOS.
 - SysML v2 parsing, semantic analysis, and standard library are provided by the Language and
-  Stdlib assemblies; the Core assembly contains only Filtering, Layout, Rendering, and Io
-  concerns.
+  Stdlib assemblies; the Core assembly contains only Filtering, Layout, Rendering, Query, and
+  Io concerns.