Add query dependencies verb and enhance CLI flags for Markdown

.reviewmark.yaml

@@ -902,6 +902,20 @@ 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:

CONTRIBUTING.md

@@ -239,7 +239,7 @@ Examples:
 
 - `Add support for custom report headers`
 - `Fix crash when results file path is invalid`
-- `Update documentation for --report-depth option`
+- `Update documentation for --walk-depth option`
 - `Refactor argument parsing for better testability`
 
 ## Pull Request Process

README.md

@@ -27,8 +27,9 @@ documentation, CI/CD pipelines, and AI-assisted modeling workflows.
 - **`lint` Command**: Load a workspace and report all diagnostics; exit non-zero if errors
   are present — suitable for CI/CD and AI-assisted model-fix loops
 - **`render` Command**: Load a workspace, resolve a view, and render to SVG or PNG
-- **`query` Command**: 11 model-analysis verbs (`uses`, `used-by`, `impact`, `describe`,
-  `hierarchy`, `requirements`, `interface`, `connections`, `states`, `list`, `find`) for AI
+- **`query` Command**: 12 model-analysis verbs (`uses`, `used-by`, `dependencies`, `impact`,
+  `describe`, `hierarchy`, `requirements`, `interface`, `connections`, `states`, `list`,
+  `find`) for AI
   and human callers, with Markdown or JSON output — designed so an AI agent can query
   architecture and traceability facts directly instead of reading raw `.sysml` files
 - **`export` Command**: Dumps the resolved semantic model (declarations, edges,
@@ -94,7 +95,7 @@ sysml2tools render "src/**/*.sysml" --view SystemContext --output out --format s
 sysml2tools render model.sysml --auto --output out --format svg
 
 # Limit nesting depth (truncated parts show "+N more…")
-sysml2tools render model.sysml --output out --depth 3
+sysml2tools render model.sysml --output out --walk-depth 3
 
 # Dynamic (ad-hoc) view: render any resolvable element without declaring a view def in the model
 sysml2tools render model.sysml --view-type interconnection --view-target Pkg::Engine --output out
@@ -123,6 +124,9 @@ sysml2tools query uses --element Pkg::MyPart model.sysml
 # What depends on this element? (incoming edges)
 sysml2tools query used-by --element Pkg::MyPart model.sysml
 
+# Dependencies section prose, ready to paste into design docs (combined uses/used-by)
+sysml2tools query dependencies --element Pkg::MyPart model.sysml
+
 # Fact sheet: kind, supertypes, typing, annotations, children
 sysml2tools query describe --element Pkg::MyPart model.sysml
 
@@ -207,7 +211,7 @@ sysml2tools [-v|--version] [-?|-h|--help] [--silent]
 sysml2tools help [lint|render|query [<query-verb>]|export]
 ```
 
-`<verb>` is `lint`, `render`, `export`, or `query <query-verb>` (11 query verbs — see the
+`<verb>` is `lint`, `render`, `export`, or `query <query-verb>` (12 query verbs — see the
 *Querying* section above).
 
 ### Global Options
@@ -240,7 +244,7 @@ sysml2tools help [lint|render|query [<query-verb>]|export]
 | `--view-type <kind>` | Dynamic view kind (`general`/`interconnection`/`state`/`action`/`sequence`/`grid`/`browser`) |
 | `--view-target <name>` | Qualified name of the dynamic view's target element; requires `--view-type` |
 | `--filter <expr>` | Bracket-filter expression narrowing a dynamic view's rendered scope (requires `--view-type`) |
-| `--depth <#>` | Limit rendered nesting depth; truncated parts show `+N more…` |
+| `--walk-depth <#>` | Limit rendered nesting depth; truncated parts show `+N more…` |
 
 `--view-type` and `--view-target` must be specified together, and are mutually exclusive with
 `--view`/`--auto`; `--filter` is only valid alongside `--view-type`/`--view-target`.
@@ -249,15 +253,17 @@ sysml2tools help [lint|render|query [<query-verb>]|export]
 
 | Option | Description |
 | --- | --- |
-| `<verb>` | One of the 11 supported query verbs — see the *Querying* section above |
+| `<verb>` | One of the 12 supported query verbs — see the *Querying* section above |
 | `<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`) |
-| `--depth <#>` | Maximum impact-walk depth (`impact` verb only); shares the same flag as `render`'s nesting `--depth` |
+| `--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) |
 | `--name <substring>` | Name substring filter (`list`/`find` verbs only) |
 | `--include-stdlib` | Include OMG standard library elements in results |
+| `--depth <#>` | Markdown heading depth (1-6, default: 1); Markdown output only, no effect on `--format json` |
+| `--heading <text>` | Replaces default `# query <verb>[: <element>]`; Markdown only, no effect on JSON |
 
 ### `export` Options
 
@@ -275,7 +281,7 @@ sysml2tools help [lint|render|query [<query-verb>]|export]
 | Option | Description |
 | --- | --- |
 | `[command]` | Optional: `lint`, `render`, `query`, or `export`; omit for top-level help |
-| `[verb]` | Optional; only meaningful when `command` is `query` — one of the 11 supported query verbs |
+| `[verb]` | Optional; only meaningful when `command` is `query` — one of the 12 supported query verbs |
 
 ## View Selection
 

docs/design/introduction.md

@@ -130,10 +130,19 @@ system, subsystem, and unit levels:
     `RenderCommand.PrintHelp`, `QueryCommand.PrintGeneralHelp`/`PrintVerbHelp`)
     - **HelpCommand** (Unit) — parses the optional target command/verb and dispatches to that
       command's help-printing method
+  - **Query** (Subsystem) — query command implementation: resolves a workspace, runs one of the
+    query verbs (`uses`, `used-by`, `dependencies`, `impact`, `describe`, `hierarchy`,
+    `requirements`, `interface`, `connections`, `states`, `list`, `find`) against it, and renders
+    the result as a Markdown or JSON `QueryResult`
+    - **QueryCommand** (Unit) — delegates glob pattern resolution to `GlobFileCollector`, loads
+      workspace with stdlib seed, dispatches to `QueryEngine` and `QueryResultRenderer`
   - **SelfTest** (Subsystem) — self-validation test runner
     - **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:**
 

docs/design/sysml2-tools-tool.md

@@ -60,10 +60,15 @@ self-testing, and uses `PathHelpers` to construct safe temporary file paths.
 - *Type*: CLI.
 - *Role*: Consumer (the host environment invokes the system with command-line arguments).
 - *Contract*: Accepts arguments `-v`/`--version`, `-?`/`-h`/`--help`, `--silent`, `--validate`,
-  `--results <file>`, `--result <file>` (legacy alias for `--results`), `--depth <n>`, and
-  `--log <file>`. Accepts `lint <patterns...>` as a subcommand that invokes lint mode. Accepts
-  `query <verb> [options] <patterns...>` (11 verbs; `--element`/`-e`, `--format`,
-  `--direction`, `--kind`, `--name`, `--include-stdlib` options). Accepts
+  `--results <file>`, `--result <file>` (legacy alias for `--results`), `--depth <n>` (Markdown
+  heading depth, shared by `--validate` and `query`), `--heading <text>` (Markdown heading text
+  override, shared by `query`), and `--log <file>`. Accepts `lint <patterns...>` as a subcommand
+  that invokes lint mode. Accepts `render [options] <patterns...>` (`--walk-depth <n>` controls
+  diagram-nesting depth) as a subcommand that renders diagrams. Accepts `help [subcommand]` as a
+  subcommand (equivalent to `--help`/`-?`/`-h`) that prints general or per-subcommand usage
+  text. Accepts `query <verb> [options] <patterns...>` (12 verbs; `--element`/`-e`, `--format`,
+  `--direction`, `--kind`, `--name`, `--include-stdlib`, `--walk-depth` (bounded-traversal depth,
+  meaningful only for the `impact` verb) options). Accepts
   `export [options] <patterns...>` (`--format json|jsonl`, `--output <file>`,
   `--include-stdlib` options) which dumps the resolved semantic model (declarations, edges,
   diagnostics) as JSON or JSON Lines. Returns

docs/design/sysml2-tools-tool/cli/context.md

@@ -19,14 +19,27 @@ grammar, rather than sharing one mega-switch across `lint`/`render`/`query`:
    command's own grammar, rejecting any flag it does not recognize with an `ArgumentException`
    naming both the flag and the command.
 
-**Design decision — `--depth` is a global option, not scoped to `render`:** although `--depth`
-semantically feeds `render`'s diagram nesting depth and `query`'s `impact`-walk depth, it must
-also work with **no command at all** (`sysml2tools --validate --depth 2`, which adjusts
-`HeadingDepth` for the self-validation report). Because of this bare-invocation requirement,
-`--depth` is parsed once by `GlobalArgumentParser` (feeding `Context.HeadingDepth`/
-`Context.MaxRenderDepth`) and the same raw value is threaded into `QueryOptions.Depth` by
-`Context.Create` when dispatching to `QueryArgumentParser`. This is a deliberate exception to the
-general per-command-scoping principle, justified by the pre-existing bare-`--depth` behavior.
+**Design decision — walk/nesting depth is per-command-scoped:** `render`'s diagram nesting
+depth and `query`'s `impact`-walk depth are both parsed locally, as `--walk-depth`, by
+`RenderArgumentParser`/`QueryArgumentParser` respectively — an ordinary command-scoped flag
+like any other, with no special-cased global plumbing. The global `--depth` flag is a
+separate, unrelated concept: Markdown heading depth, feeding `Context.HeadingDepth`. It must
+work with **no command at all** (`sysml2tools --validate --depth 2`, which adjusts
+`HeadingDepth` for the self-validation report), and `query` also reads it directly
+(`Context.HeadingDepth`) for its own Markdown report heading depth — this is the only
+cross-command reuse of `--depth`, and it is a direct read of the already-parsed global value,
+not a second parse.
+
+**Design decision — `--heading` is intentionally query-scoped, not global:** unlike `--depth`,
+the `--heading <text>` override (custom Markdown heading text) is parsed entirely within
+`QueryArgumentParser` and stored on `QueryOptions.Heading`; it is **not** a `Context`/
+`GlobalArgumentParser` concept and has no effect on `--validate`. This is deliberate: `--depth`
+needed global scope because `--validate`'s self-validation report predates `query` and already
+used the shared `Context.HeadingDepth` flag, but a custom heading *title* is only meaningful for
+`query`'s report-style output (e.g. pasting a `query dependencies` result into a design doc under
+a caller-chosen heading) — `--validate`'s self-validation summary has no equivalent "custom title"
+use case, so promoting `--heading` into the shared global layer would add unused surface area to
+`lint`/`render`/`--validate` for no current benefit.
 
 #### Data Model
 
@@ -47,12 +60,9 @@ to `false` within the same invocation.
 neither flag was present.
 
 **HeadingDepth**: `int` — Heading depth for markdown output; valid range 1–6, default 1;
-supplied via `--depth`. Parsed by `GlobalArgumentParser` (see design decision above).
-
-**MaxRenderDepth**: `int?` — Raw diagram render depth supplied via `--depth`; not clamped
-to 6. `null` when `--depth` was not specified. Used by the render command as the
-`DepthLimit` in `RenderOptions`, and threaded into `Query.Depth` for the `query` command's
-`impact` verb; 0 is interpreted as unlimited.
+supplied via `--depth`. Parsed by `GlobalArgumentParser` (see design decision above); read
+directly by `SelfTest/Validation.cs` (self-validation report) and `QueryCommand.RunAsync`
+(query's Markdown report heading depth).
 
 **Command**: `SysmlCommand` — `SysmlCommand.Lint` when `lint` is the first recognized command
 token; `SysmlCommand.Render` when `render` is the first recognized command token;
@@ -65,7 +75,8 @@ its own file, `Cli/SysmlCommand.cs`.
 
 **Render**: `RenderCommandOptions?` — populated only when `Command` is `SysmlCommand.Render`.
 Carries `OutputDirectory`, `Format` (`"svg"`/`"png"`, validated by `RenderCommand.RunAsync` — not
-at parse time), `ViewName`, `AutoView`, and `Files`. Named `RenderCommandOptions` rather than
+at parse time), `ViewName`, `AutoView`, `WalkDepth` (diagram nesting depth limit, command-scoped),
+and `Files`. Named `RenderCommandOptions` rather than
 `RenderOptions` to avoid colliding with `DemaConsulting.Rendering.Abstractions.RenderOptions`,
 the off-the-shelf rendering-library type already used inside `RenderCommand`.
 
@@ -74,7 +85,8 @@ recognized verb token was captured; `null` when `query` was supplied without a v
 `--help` was requested (e.g., `query --help`), or when a different command was selected.
 Carries `--element`/`-e`, `--direction`, `--kind`, `--name`, `--include-stdlib`, the query's own
 `--format` (`"markdown"`/`"json"`, a value independent of `render`'s `--format` even though the
-flag name is shared), the `Depth` value threaded from the global `--depth`, and the
+flag name is shared), `WalkDepth` (impact-walk depth, command-scoped, parsed from `query`'s own
+`--walk-depth`), `Heading` (custom Markdown heading text from `--heading`), and the
 query-specific `Files` list.
 
 **HelpCommand**: `HelpOptions?` — populated only when `Command` is `SysmlCommand.Help`. Named
@@ -100,7 +112,7 @@ switches on `GlobalArguments.Command` to dispatch to exactly one per-command par
 
 - `SysmlCommand.Lint` → `LintArgumentParser.Parse(global.CommandArgs)` → `Lint`.
 - `SysmlCommand.Render` → `RenderArgumentParser.Parse(global.CommandArgs)` → `Render`.
-- `SysmlCommand.Query` → `QueryArgumentParser.Parse(global.CommandArgs, global.Help, global.MaxRenderDepth)`
+- `SysmlCommand.Query` → `QueryArgumentParser.Parse(global.CommandArgs, global.Help)`
   → `Query`. The `query` grammar is **structural**: the first token after the `query` command
   token must be a recognized verb (validated eagerly via `QueryVerbParsing.Parse`, which lists all
   valid tokens on failure); when no verb token is present, parsing returns `null` if `--help` was
@@ -176,7 +188,7 @@ available.
 - **Program** — creates `Context` via `Context.Create` and calls `WriteLine` and `WriteError`.
 - **Validation** — receives `Context` from `Program` and calls `WriteLine` and `WriteError`.
 - **LintCommand** — reads `Lint` (`LintOptions`); calls `WriteLine` and `WriteError`.
-- **RenderCommand** — reads `Render` (`RenderCommandOptions`) and `MaxRenderDepth`; calls
+- **RenderCommand** — reads `Render` (`RenderCommandOptions`); calls
   `WriteLine` and `WriteError`.
 - **QueryCommand** — reads `Query` (`QueryOptions`); calls `WriteLine` and `WriteError`.
 - **HelpCommand** — reads `HelpCommand` (`HelpOptions`); dispatches to

docs/design/sysml2-tools-tool/help.md

@@ -12,7 +12,7 @@ It provides three cooperating types:
 - `HelpArgumentParser` — parses the arguments following the `help` command token: an optional
   first token naming the target command, followed — only when the target is `query` — by an
   optional second token naming the verb, re-validated via `QueryVerbParsing.Parse` rather than
-  duplicating the 11-verb vocabulary.
+  duplicating the 12-verb vocabulary.
 - `HelpCommand` — pure dispatch. `Run(Context)` never authors help text itself; it delegates to
   the single source of truth for each command's help text: `Program.PrintTopLevelHelp`,
   `LintCommand.PrintHelp`, `RenderCommand.PrintHelp`, or
@@ -102,7 +102,7 @@ help text. Authors no help text of its own.
 - Unrecognized target command (`help bogus`): `ArgumentException` (thrown by
   `HelpArgumentParser.Parse`) listing the three valid targets.
 - Unrecognized query verb (`help query bogus`): `ArgumentException` (thrown by
-  `QueryVerbParsing.Parse`, reused as-is) listing all 11 valid verb tokens.
+  `QueryVerbParsing.Parse`, reused as-is) listing all 12 valid verb tokens.
 - Extra/`-`-prefixed trailing token: `ArgumentException` naming the bad token and the `help`
   command.
 - All three cases propagate to `Program.Main`'s existing `ArgumentException` handler, which