From 15934ea21d5d43fdd5d643a09978580c628a5241 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 21:21:11 -0400 Subject: [PATCH 1/7] chore: sync agents, standards, and skills for sysml2 design work Manually synchronize agent, standards, and skill files in preparation for adding sysml2 architecture model design information. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/template-sync.agent.md | 2 + .github/skills/sysml2tools-query/SKILL.md | 145 +++++++++++++ .github/standards/design-documentation.md | 5 +- .github/standards/reviewmark-usage.md | 16 +- .github/standards/software-items.md | 5 + .github/standards/sysml2-modeling.md | 235 ++++++++++++++++++++++ AGENTS.md | 15 +- 7 files changed, 412 insertions(+), 11 deletions(-) create mode 100644 .github/skills/sysml2tools-query/SKILL.md create mode 100644 .github/standards/sysml2-modeling.md diff --git a/.github/agents/template-sync.agent.md b/.github/agents/template-sync.agent.md index df4d488..baf5fa8 100644 --- a/.github/agents/template-sync.agent.md +++ b/.github/agents/template-sync.agent.md @@ -21,6 +21,8 @@ Delegate each group to a sub-agent. # Work Groups - **Root config files** - all non-collection files at the repository root +- **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder, + not a Pandoc collection) - **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/` - **One group for root files in each of `docs/design/`, `docs/verification/`, `docs/reqstream/`** - e.g. `docs/design/introduction.md` — separate from the diff --git a/.github/skills/sysml2tools-query/SKILL.md b/.github/skills/sysml2tools-query/SKILL.md new file mode 100644 index 0000000..f754338 --- /dev/null +++ b/.github/skills/sysml2tools-query/SKILL.md @@ -0,0 +1,145 @@ +--- +name: sysml2tools-query +description: Query this repository's SysML2 architecture model (docs/sysml2/) to understand software structure, purpose, and relationships before deep-diving into source code. Use this when asked to understand the codebase, find which unit implements something, assess the impact of a change, or trace requirements to code. +--- + +# SysML2Tools Query Skill + +This repository models its software structure in SysML2 under `docs/sysml2/`. Prefer +querying this model over grepping/reading source files when you need to understand +*what* a piece of the system is, *why* it exists, or *what it depends on*. + +## Prerequisites + +The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`. +Restore it once per session if not already available: + +```pwsh +dotnet tool restore +``` + +## Model files + +- `docs/sysml2/model/{system-name}.sysml` — system-level `part def` only (no subsystems/units + inline). A repository may contain more than one system. +- `docs/sysml2/model/{system-name}/{subsystem-name}.sysml` and + `docs/sysml2/model/{system-name}/{subsystem-name}/{unit-name}.sysml` — one file per + Subsystem/Unit, nested to mirror the same folder depth as that item's companion + `docs/design/`, `docs/reqstream/`, and `docs/verification/` files. +- `docs/sysml2/model/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items + exist). +- `docs/sysml2/model/shared.sysml` — Shared Package parts (present when Shared Package items + exist). +- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document; a + sibling of `model/`, not nested inside it. Not usually needed for query workflows, but + useful to see how diagrams are scoped. + +Always pass all `.sysml` files (or a glob covering them) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files that +reopen the same `package Name { ... }` from different files merge into one namespace +automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand +(`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses +correctly — pass a single **quoted** glob string and let the tool resolve it, rather than +relying on the shell (quoting works identically in both PowerShell and bash): + +```pwsh +dotnet sysml2tools query list 'docs/sysml2/model/**/*.sysml' +``` + +## Artifact-location metadata + +Every System/Subsystem/Unit `part def` carries named `comment` elements pointing at its +companion artifacts (source, test, design, verification, and — for repositories that still +use ReqStream — requirements file). `query describe` returns every comment attached to +an element, so one query gets you every artifact location for that item without grepping the +source tree: + +```pwsh +dotnet sysml2tools query describe -e {SystemName}::{UnitName} 'docs/sysml2/model/**/*.sysml' +``` + +```text +- Documentation: One-line purpose statement for the unit. +- Comment: Source: src/{Project}/{Subsystem}/{UnitName}.cs +- Comment: Test: test/{Project}.Tests/{Subsystem}/{UnitName}Tests.cs +- Comment: Design: docs/design/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Verification: docs/verification/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Requirements: docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml +``` + +Not every item has all five comments — Systems/Subsystems have no `Source` comment, and +units without a dedicated companion doc point at their parent's doc instead (see the +Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these +paths over guessing a file location from the unit name; fall back to `grep`/`glob` only when +a comment is missing or the model is stale. + +## Recommended workflow + +1. **Discover the system(s) present** — do not assume a fixed name: + + ```pwsh + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + + Look for the top-level part def with no containing part (or the one with the most + children) to identify each system's qualified name. + +2. **Get the full hierarchy** (subsystems and units) for a system found above: + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + + `describe` lists direct children and every artifact-location comment; repeat on each + child to walk deeper, or use `query list` to see the full flat inventory. + +3. **Understand a specific unit's purpose and find its files** before opening its source + file — `describe` returns both the purpose `doc` and every `Comment:` artifact-location + line in one call (see Artifact-location metadata above): + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + +4. **Assess impact before editing a unit** — see what depends on it: + + ```pwsh + dotnet sysml2tools query used-by -e 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query impact -e 'docs/sysml2/model/**/*.sysml' + ``` + + Note: this only surfaces structural (typing/containment) references modeled in + `.sysml` — not full call-graph/behavioral dependencies. Confirm actual usage in source + before making impact-sensitive changes. + +5. **Trace requirements** linked to a unit, if modeled: + + ```pwsh + dotnet sysml2tools query requirements -e 'docs/sysml2/model/**/*.sysml' + ``` + +6. **Search by name or kind** when the qualified name is unknown: + + ```pwsh + dotnet sysml2tools query find --name 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + +Use `--format json` on any query verb for machine-parsed output. + +## Fallback + +If the model is stale, doesn't yet cover a unit, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When you finish work that adds or changes a +Unit/Subsystem, update the corresponding `.sysml` model file (including its artifact-location +comments) in the same change (mirrors the existing requirement to keep `docs/design/*.md` and +`docs/reqstream/*.yaml` companion artifacts in sync). See the `sysml2-modeling.md` +standard for full modeling and view-authoring conventions. + +## Validating changes to the model + +Before committing changes to any `.sysml` file, lint it: + +```pwsh +dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' +``` diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index 4d413c6..c6f107f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -8,6 +8,8 @@ globs: ["docs/design/**/*.md"] - **`technical-documentation.md`** - General technical documentation standards - **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`sysml2-modeling.md`** - SysML2 model and view conventions feeding the Software Structure + section # Folder Structure @@ -37,7 +39,8 @@ Must include: - **Purpose**: audience and compliance drivers - **Scope**: items covered and explicitly excluded (no test projects) -- **Software Structure**: text tree showing all Systems/Subsystems/Units/OTS/Shared items +- **Software Structure**: diagram(s) rendered from the SysML2 model under `docs/sysml2/`, + per `sysml2-modeling.md` — not a hand-maintained text tree - **Folder Layout**: text tree showing source folder structure - **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests - **References** _(if applicable)_: external standards or specifications - only in `introduction.md` diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index 1ac5846..bc73da6 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -20,7 +20,8 @@ review, organizes them into review-sets, and generates review plans and reports. - **Lint Configuration**: `dotnet reviewmark --lint` - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}` -- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce` (exits non-zero if any files are uncovered) +- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce` + (exits non-zero if any files are uncovered) ## Repository Structure @@ -39,6 +40,7 @@ needs-review: - "!**/obj/**" - "requirements.yaml" - "docs/reqstream/**/*.yaml" + - "docs/sysml2/**/*.sysml" - "README.md" - "docs/user_guide/**/*.md" - "docs/design/**/*.md" @@ -97,7 +99,7 @@ as global context. | `{SystemName}-AllRequirements` | Parent system design doc + `docs/reqstream/{system-name}.yaml` | | `{SystemName}-{UnitName}` (direct unit) | Parent system design doc + parent system requirements | | `{SystemName}-{SubsystemName}` (subsystem) | Parent system design doc + parent system requirements | -| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs, system + subsystem requirements | +| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs + requirements | # Review-Set Organization @@ -119,13 +121,16 @@ placeholders are always PascalCase (e.g., `{SystemName}`). ## `Decomposition` Review (only one per repository) -- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing promise; the structural mirror of the decomposition decision +- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing + promise; the structural mirror of the decomposition decision - **Title**: "Review that {SystemName} Decomposition Addresses the Stated Purpose" - **ID**: `Decomposition` (no system prefix — one per repository) -- **Scope**: introduction.md (the decomposition narrative) and requirements.yaml (the structural tree); no system-level detail +- **Scope**: introduction.md (the decomposition narrative), the SysML2 model (the + authoritative structural tree), and requirements.yaml; no system-level detail - **File Path Patterns**: - Root requirements: `requirements.yaml` - Design introduction: `docs/design/introduction.md` + - SysML2 model: `docs/sysml2/**/*.sysml` - **Context Files**: `README.md`, `docs/user_guide/**/*.md` ## `{SystemName}-Architecture` Review (one per system) @@ -205,7 +210,8 @@ placeholders are always PascalCase (e.g., `{SystemName}`). - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs` - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp` -- **Context Files**: Parent system design + requirements; add subsystem design + requirements for each subsystem level above the unit. +- **Context Files**: Parent system design + requirements; add subsystem design + + requirements for each subsystem level above the unit. ## `OTS-{OtsName}` Review (one per OTS item) diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 6c29525..3514228 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -130,3 +130,8 @@ the item is correct, well-designed, and proven to work: - **Verification Design** - HOW the requirements will be tested (applies to all item types) - **Source code** - The implementation of the design (local units only; not applicable to OTS or Shared Package) - **Tests** - PROOF the item does WHAT it is required to do (applies to all item types) + +Where the repository models its software structure in SysML2, each item's part def carries +`comment` metadata pointing at these same artifact locations (`sourceRef`/`testRef`/ +`designRef`/`verificationRef`/`reqRef`) so agents can query them directly — see +`sysml2-modeling.md`. diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md new file mode 100644 index 0000000..60f7b96 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,235 @@ +--- +name: SysML2 Modeling +description: Follow these standards when creating or modifying the SysML2 architecture + model, its rendered views, or the software structure it feeds into design documentation. +globs: ["docs/sysml2/**/*.sysml"] +--- + +# SysML2 Modeling Standard + +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`design-documentation.md`** - Design document structure that embeds the diagrams this + standard produces + +## Purpose + +The repository's software structure is modeled in SysML2 under `docs/sysml2/` rather than +hand-maintained as prose or an ASCII tree. The model is the authoritative, machine-queryable +source of structure; rendered diagrams and `docs/design/introduction.md`'s narrative are +generated/derived artifacts. AI agents should query the model (see `sysml2tools-query` +skill) before deep-diving into source code to understand what a piece of the system is, +why it exists, and what it depends on. + +## Repository Structure + +```text +docs/sysml2/ +├── model/ +│ ├── {system-name}.sysml # system-level part def only (no subsystems/units inline) +│ ├── {system-name}/ +│ │ ├── {subsystem-name}.sysml # subsystem part def; nests further for sub-subsystems +│ │ └── {subsystem-name}/ +│ │ └── {unit-name}.sysml # one file per unit +│ ├── ots.sysml # OTS dependency parts (optional; if OTS items exist) +│ └── shared.sysml # Shared Package parts (optional; if Shared Packages exist) +└── views/ + └── design-views.sysml # named view usages rendered for the design document +``` + +`docs/sysml2/model/` mirrors the same folder shape as `docs/design/`, `docs/reqstream/`, and +`docs/verification/` — one `.sysml` file per System/Subsystem/Unit, at the same nesting depth +as that item's companion design/requirements/verification files. This keeps each file small +and keeps PRs that touch one unit's model from producing unrelated diffs in unrelated units. +`docs/sysml2/views/` is a sibling of `model/`, not nested inside it, so a single +`docs/sysml2/model/**/*.sysml` glob never needs to exclude view files (`sysml2tools` has no +exclude-glob syntax). + +There is no separate "stable entry point" file — a repository may contain multiple systems, +so no single alias name would generalize. Agents discover the system(s) present by running +`query list --kind "part def"` or `query find` (see the `sysml2tools-query` skill) over +`docs/sysml2/model/**/*.sysml`, not by assuming a fixed name. + +Always pass the full set of `.sysml` files (or an equivalent glob) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files sharing +the same `package Name { ... }` merge into one namespace automatically with no `import` +required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5, +`lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into +subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) +and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip +the pattern before it reaches the tool. Quoting keeps the behavior identical across +PowerShell and bash, since neither shell needs to (or reliably does) expand `**` itself. + +## Model Content + +- `{system-name}.sysml` defines one `part def` for the System only, with `part` usages + referencing its direct Subsystems/Units (defined in their own files, see below). +- Each `{subsystem-name}.sysml` / `{unit-name}.sysml` defines exactly one `part def`, with a + `doc /* ... */` comment stating its purpose — mirroring what would otherwise be written as + prose in `docs/design/introduction.md`'s Software Structure section. Subsystem files add + `part` usages for their own direct children (nested subsystems or units), matching the + Software Item Hierarchy in `software-items.md`. +- `ots.sysml` / `shared.sysml` define one `part def` per OTS item / Shared Package, referenced + as `part` usages from the system(s) that depend on them. + +## Artifact-Location Comments + +Every System/Subsystem/Unit `part def` records where its companion artifacts live, as named +`comment` elements — not `attribute`s (attribute values are not surfaced by `sysml2tools query +describe`, even in JSON output; comments are). Comments have zero effect on rendered diagrams +(verified: a part def with several comments attached renders with no extra nodes or size +change) and are fully returned by `query describe`, in declaration order, as +`Comment: ...` summary lines — this is how an agent gets every artifact location for a unit +in a single query, without grepping the source tree. + +Use these comment names, in this order, when applicable to the item: + +```sysml +part def {UnitName} { + doc /* One-line purpose statement. */ + + comment sourceRef /* Source: {path to the unit's source file} */ + comment testRef /* Test: {path to the unit's test file} */ + comment designRef /* Design: {path to the unit's design doc} */ + comment verificationRef /* Verification: {path to the unit's verification doc} */ + comment reqRef /* Requirements: {path to the unit's reqstream file} */ +} +``` + +Not every item has all five: + +- **Systems and Subsystems** have no `sourceRef` (no single source file represents a whole + system or subsystem) — use `testRef` for the subsystem-level test file when one exists. +- **Units without a dedicated companion doc** (e.g. small data-model types documented inline + within their subsystem's design doc rather than in their own file) point `designRef` / + `verificationRef` / `reqRef` at the subsystem-level doc, with a short parenthetical note, + e.g. `/* Design: docs/design/{system}/{subsystem}.md (documented as a supporting value type) */`. +- **Units without a dedicated test file** (exercised only indirectly through another unit's + tests) omit `testRef` entirely rather than pointing at an unrelated test file. +- **OTS items** have no `sourceRef`/`testRef` (no local integration code); use `designRef` + (when the optional design doc exists) / `verificationRef` / `reqRef` only. + +This is prose-searchable metadata only — it is not a substitute for the authoritative +requirements/design/verification artifacts, and it does not replace ReqStream as the +requirements source of truth. (This repository currently keeps requirements traceability in +ReqStream; a future migration to native SysML2 `requirement`/`satisfy` modeling is a separate, +not-yet-scheduled change.) + +## Views (`docs/sysml2/views/design-views.sysml`) + +Views control what gets rendered into diagrams for the design document. Use named `view` +**usages** (not `view def` **definitions**) — `expose` is only valid inside a usage: + +```sysml +package {SystemName} { + view SoftwareStructureView { + expose {SystemName}; // whole package: system + subsystems + units + render asTreeDiagram; + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + render asTreeDiagram; + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + render asTreeDiagram; + } +} +``` + +**Critical distinction** (do not confuse these — this cost significant trial-and-error to +discover): `expose ;` is what scopes a rendered diagram's content (the union of the +named element's containment subtree). `render ;` selects a rendering *style* (e.g. +`asTreeDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }` +**definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not +dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`). + +**Naming convention** — one `View` suffix per rendered diagram, no `System`/`Subsystem` +suffix duplication: + +- `SoftwareStructureView` - full detail: every system, subsystem, and unit in one diagram +- `{SystemName}View` - one per system, direct members only (not expanded into subsystems) +- `{SubsystemName}View` - one per subsystem (at any nesting depth), that subsystem's own + members only + +When a repository has multiple systems, `SoftwareStructureView` may expose each system's +package individually (`expose {SystemNameA}; expose {SystemNameB};`) or the whole workspace, +whichever produces a single coherent overview diagram. + +## Diagram Embedding + +Render with a single quoted recursive glob for the model tree, plus the views file +(`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing +or explicit per-file listing is needed): + +```pwsh +dotnet sysml2tools render ` + --output docs/design/generated --format svg ` + 'docs/sysml2/model/**/*.sysml' ` + 'docs/sysml2/views/design-views.sysml' +``` + +With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view +in one invocation, one file per view, using each view's own name as the filename +(`{ViewName}.svg`) — no post-render rename step is needed. + +Embed diagrams in `docs/design/` per this rule: every design doc for an item embeds the +diagram for the narrowest view that still shows that item's own immediate structure — + +- `docs/design/introduction.md` — `SoftwareStructureView.svg` (the full-detail overview) +- `docs/design/{system-name}.md` and every unit doc for a unit directly under the system + (no subsystem parent) — `{SystemName}View.svg` +- `docs/design/{system-name}/{subsystem-name}.md` and every unit doc nested under that + subsystem (at any depth) — `{SubsystemName}View.svg` + +Place the image directly under the file's top-level heading, before its first prose +subsection, e.g. `![{Name} Structure]({ViewName}.svg)`. + +## Build and Lint Integration + +- `sysml2tools lint` belongs in `lint.ps1`'s compliance-tools section, **not** as a separate + step in the CI design-document job — `lint.ps1` gates every later job (including document + generation) transitively, so linting the model there is both earlier and non-duplicated. + Pass a single quoted recursive glob, e.g. `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` + — `sysml2tools` (0.1.0-beta.5+) expands and recurses this itself, so no + `Get-ChildItem`/shell-side globbing is needed. +- The CI design-document job renders the views (see the render command above) before running + Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds + are unnecessary since view names are stable by definition. Pass the model and views globs as + separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`) + — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar` + workaround is needed. +- Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to + `.versionmark.yaml`'s captured tool list. + +## Fallback + +If the model is stale, doesn't yet cover an item, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When work adds or changes a Unit/Subsystem, +update the corresponding `.sysml` model file in the same change — this mirrors the existing +requirement to keep `docs/design/*.md` and `docs/reqstream/*.yaml` companion artifacts in +sync. + +## Quality Checks + +- [ ] Every System/Subsystem/Unit in `docs/design/introduction.md` has a matching `part def` + in its own file under `docs/sysml2/model/`, at the same folder depth as its companion + design/reqstream/verification files, with a purpose `doc` comment +- [ ] Every Unit-level `part def` has `sourceRef`/`testRef`/`designRef`/`verificationRef`/ + `reqRef` comments where applicable (see Artifact-Location Comments for documented + exceptions); System/Subsystem `part def`s have `testRef`/`designRef`/`verificationRef`/ + `reqRef` but no `sourceRef` +- [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not + `view def` definitions +- [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` / + `{SubsystemName}View` convention +- [ ] `sysml2tools lint` passes on all `.sysml` files +- [ ] Rendered diagrams are embedded in every design doc per the Diagram Embedding rule +- [ ] `sysml2tools` is present in `lint.ps1`, `.config/dotnet-tools.json`, and + `.versionmark.yaml` diff --git a/AGENTS.md b/AGENTS.md index 3766d7d..8aaa831 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,7 @@ │ ├── requirements_doc/ │ ├── requirements_report/ │ ├── reqstream/ +│ ├── sysml2/ │ ├── user_guide/ │ └── verification/ ├── src/ @@ -55,10 +56,12 @@ This repository follows a reference template for structure and file conventions. # Codebase Navigation (ALL Agents) -When working with source code, design, or requirements artifacts, read -`docs/design/introduction.md` first. It provides the software structure, -folder layout, and companion artifact locations. Use it as the primary map -before searching the filesystem. +When working with source code, design, or requirements artifacts, query the SysML2 +architecture model under `docs/sysml2/` first (see the `sysml2tools-query` skill) to +understand software structure, purpose, and relationships. Fall back to +`docs/design/introduction.md` for the human-facing narrative, folder layout, and +companion artifact locations, and use it as the primary map when the model doesn't +yet cover something. # Key Configuration Files @@ -73,6 +76,7 @@ before searching the filesystem. - **`package.json`** - Node.js dependencies for formatting tools - **`requirements.yaml`** - Root requirements file with includes - **`pip-requirements.txt`** - Python dependencies for yamllint and yamlfix +- **`docs/sysml2/`** - SysML2 architecture model; authoritative source for software structure - **`fix.ps1`** - Applies all auto-fixers silently (dotnet format, markdown, YAML). Always exits 0. - **`build.ps1`** - Builds the solution and runs all tests. @@ -89,6 +93,7 @@ from `.github/standards/`. Use this matrix to determine which to load: - **Design docs**: `software-items.md`, `design-documentation.md`, `technical-documentation.md` - **Verification docs**: `software-items.md`, `verification-documentation.md`, `technical-documentation.md` - **Review configuration**: `software-items.md`, `reviewmark-usage.md` +- **Software structure**: `sysml2-modeling.md` - **Any documentation**: `technical-documentation.md` Load only the standards relevant to your specific task scope. @@ -143,7 +148,7 @@ responsibility - invoke the lint-fix agent once before submitting a pull request ## CI Quality Tools CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format, -reqstream, versionmark, and reviewmark. +reqstream, versionmark, reviewmark, and sysml2tools. # Scope Discipline (ALL Agents Must Follow) From 1ba05f0c479140df4eaaef1f75a96e7b26f2a7e6 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 21:40:13 -0400 Subject: [PATCH 2/7] chore: sync lint.ps1 and .yamlfix.toml with template - Add Test-Path-guarded sysml2tools lint block to lint.ps1, matching the check AGENTS.md's CI Quality Tools section already documents as active (safe no-op until docs/sysml2/ exists) - Add line_length = 10000 to .yamlfix.toml to match the template and avoid yamlfix wrapping long YAML lines against .yamllint.yaml Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .yamlfix.toml | 1 + lint.ps1 | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/.yamlfix.toml b/.yamlfix.toml index 6de1583..aff88f3 100644 --- a/.yamlfix.toml +++ b/.yamlfix.toml @@ -1,4 +1,5 @@ # YAML Auto-Fix Configuration +line_length = 10000 preserve_quotes = true sequence_style = "keep_style" whitelines = 1 diff --git a/lint.ps1 b/lint.ps1 index 26d84ff..b4bf604 100644 --- a/lint.ps1 +++ b/lint.ps1 @@ -89,6 +89,11 @@ if (-not $skipDotnetTools) { dotnet reviewmark --lint if ($LASTEXITCODE -ne 0) { $lintError = $true } + + if (Test-Path docs/sysml2) { + dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' + if ($LASTEXITCODE -ne 0) { $lintError = $true } + } } # [PROJECT-SPECIFIC] Add additional dotnet tool checks here. From 80edc3d89c544ad4f66e11a5c714b89fe36f6239 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:02:54 -0400 Subject: [PATCH 3/7] Scaffold SysML2 architecture model under docs/sysml2/ Adds docs/sysml2/model/ (one .sysml file per System/Subsystem/Unit plus ots.sysml for the 6 OTS dependencies) and docs/sysml2/views/design-views.sysml (SoftwareStructureView + one per-system view + CliView/SelfTestView, 9 views total). Wires sysml2tools into .config/dotnet-tools.json, .versionmark.yaml, and the build-docs job in .github/workflows/build.yaml (render step before Pandoc HTML generation, plus versionmark capture). Embeds the rendered Structure diagrams into the corresponding docs/design/ files, adds sysml to .cspell.yaml, and adds docs/sysml2/**/*.sysml to .reviewmark.yaml's needs-review list and Decomposition review-set. Validated: dotnet sysml2tools lint (0 errors), dotnet sysml2tools render (9 SVGs produced), dotnet sysml2tools query list --kind "part def" (49 part defs, matching introduction.md's Software Structure tree), and pwsh ./fix.ps1 / pwsh ./lint.ps1 (no new failures). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 7 ++ .cspell.yaml | 1 + .github/workflows/build.yaml | 10 ++- .reviewmark.yaml | 2 + .versionmark.yaml | 5 ++ docs/design/api-mark-core.md | 2 + docs/design/api-mark-core/emit-config.md | 2 + .../file-markdown-writer-factory.md | 2 + .../api-mark-core/file-markdown-writer.md | 2 + .../api-mark-core/glob-file-collector.md | 2 + docs/design/api-mark-core/i-api-emitter.md | 2 + docs/design/api-mark-core/i-api-generator.md | 2 + docs/design/api-mark-core/i-context.md | 2 + .../i-markdown-writer-factory.md | 2 + .../design/api-mark-core/i-markdown-writer.md | 2 + docs/design/api-mark-core/path-helpers.md | 2 + docs/design/api-mark-cpp.md | 2 + docs/design/api-mark-cpp/clang-ast-parser.md | 2 + docs/design/api-mark-cpp/cpp-ast-model.md | 2 + .../cpp-emitter-gradual-disclosure.md | 2 + .../api-mark-cpp/cpp-emitter-single-file.md | 2 + docs/design/api-mark-cpp/cpp-emitter.md | 2 + docs/design/api-mark-cpp/cpp-generator.md | 2 + .../api-mark-cpp/cpp-type-link-resolver.md | 2 + docs/design/api-mark-dot-net.md | 2 + .../api-mark-dot-net/dot-net-ast-model.md | 2 + .../dot-net-emitter-gradual-disclosure.md | 2 + .../dot-net-emitter-single-file.md | 2 + .../api-mark-dot-net/dot-net-emitter.md | 2 + .../api-mark-dot-net/dot-net-generator.md | 2 + .../api-mark-dot-net/type-link-resolver.md | 2 + .../api-mark-dot-net/type-name-simplifier.md | 2 + .../design/api-mark-dot-net/xml-doc-reader.md | 2 + docs/design/api-mark-msbuild.md | 2 + docs/design/api-mark-msbuild/api-mark-task.md | 2 + docs/design/api-mark-tool.md | 2 + docs/design/api-mark-tool/cli.md | 2 + docs/design/api-mark-tool/cli/context.md | 2 + docs/design/api-mark-tool/program.md | 2 + docs/design/api-mark-tool/self-test.md | 2 + .../api-mark-tool/self-test/validation.md | 2 + docs/design/api-mark-vhdl.md | 2 + docs/design/api-mark-vhdl/vhdl-ast-model.md | 2 + docs/design/api-mark-vhdl/vhdl-ast-parser.md | 2 + .../vhdl-emitter-gradual-disclosure.md | 2 + .../api-mark-vhdl/vhdl-emitter-single-file.md | 2 + docs/design/api-mark-vhdl/vhdl-emitter.md | 2 + docs/design/api-mark-vhdl/vhdl-generator.md | 2 + docs/design/introduction.md | 2 + docs/sysml2/model/api-mark-core.sysml | 28 ++++++++ .../model/api-mark-core/emit-config.sysml | 11 +++ .../file-markdown-writer-factory.sysml | 11 +++ .../api-mark-core/file-markdown-writer.sysml | 11 +++ .../api-mark-core/glob-file-collector.sysml | 11 +++ .../model/api-mark-core/i-api-emitter.sysml | 11 +++ .../model/api-mark-core/i-api-generator.sysml | 11 +++ .../model/api-mark-core/i-context.sysml | 11 +++ .../i-markdown-writer-factory.sysml | 11 +++ .../api-mark-core/i-markdown-writer.sysml | 11 +++ .../model/api-mark-core/path-helpers.sysml | 11 +++ docs/sysml2/model/api-mark-cpp.sysml | 25 +++++++ .../model/api-mark-cpp/clang-ast-parser.sysml | 11 +++ .../model/api-mark-cpp/cpp-ast-model.sysml | 11 +++ .../cpp-emitter-gradual-disclosure.sysml | 11 +++ .../cpp-emitter-single-file.sysml | 11 +++ .../model/api-mark-cpp/cpp-emitter.sysml | 11 +++ .../model/api-mark-cpp/cpp-generator.sysml | 11 +++ .../api-mark-cpp/cpp-type-link-resolver.sysml | 11 +++ docs/sysml2/model/api-mark-dot-net.sysml | 26 +++++++ .../api-mark-dot-net/dot-net-ast-model.sysml | 11 +++ .../dot-net-emitter-gradual-disclosure.sysml | 11 +++ .../dot-net-emitter-single-file.sysml | 11 +++ .../api-mark-dot-net/dot-net-emitter.sysml | 11 +++ .../api-mark-dot-net/dot-net-generator.sysml | 11 +++ .../api-mark-dot-net/type-link-resolver.sysml | 11 +++ .../type-name-simplifier.sysml | 11 +++ .../api-mark-dot-net/xml-doc-reader.sysml | 11 +++ docs/sysml2/model/api-mark-msbuild.sysml | 17 +++++ .../api-mark-msbuild/api-mark-task.sysml | 11 +++ docs/sysml2/model/api-mark-tool.sysml | 18 +++++ docs/sysml2/model/api-mark-tool/cli.sysml | 11 +++ .../model/api-mark-tool/cli/context.sysml | 11 +++ docs/sysml2/model/api-mark-tool/program.sysml | 11 +++ .../model/api-mark-tool/self-test.sysml | 14 ++++ .../api-mark-tool/self-test/validation.sysml | 11 +++ docs/sysml2/model/api-mark-vhdl.sysml | 24 +++++++ .../model/api-mark-vhdl/vhdl-ast-model.sysml | 10 +++ .../model/api-mark-vhdl/vhdl-ast-parser.sysml | 11 +++ .../vhdl-emitter-gradual-disclosure.sysml | 11 +++ .../vhdl-emitter-single-file.sysml | 11 +++ .../model/api-mark-vhdl/vhdl-emitter.sysml | 11 +++ .../model/api-mark-vhdl/vhdl-generator.sysml | 11 +++ docs/sysml2/model/ots.sysml | 51 ++++++++++++++ docs/sysml2/views/design-views.sysml | 68 +++++++++++++++++++ 94 files changed, 778 insertions(+), 1 deletion(-) create mode 100644 docs/sysml2/model/api-mark-core.sysml create mode 100644 docs/sysml2/model/api-mark-core/emit-config.sysml create mode 100644 docs/sysml2/model/api-mark-core/file-markdown-writer-factory.sysml create mode 100644 docs/sysml2/model/api-mark-core/file-markdown-writer.sysml create mode 100644 docs/sysml2/model/api-mark-core/glob-file-collector.sysml create mode 100644 docs/sysml2/model/api-mark-core/i-api-emitter.sysml create mode 100644 docs/sysml2/model/api-mark-core/i-api-generator.sysml create mode 100644 docs/sysml2/model/api-mark-core/i-context.sysml create mode 100644 docs/sysml2/model/api-mark-core/i-markdown-writer-factory.sysml create mode 100644 docs/sysml2/model/api-mark-core/i-markdown-writer.sysml create mode 100644 docs/sysml2/model/api-mark-core/path-helpers.sysml create mode 100644 docs/sysml2/model/api-mark-cpp.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/clang-ast-parser.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-ast-model.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-emitter-gradual-disclosure.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-emitter-single-file.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-emitter.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-generator.sysml create mode 100644 docs/sysml2/model/api-mark-cpp/cpp-type-link-resolver.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/dot-net-ast-model.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/dot-net-emitter-gradual-disclosure.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/dot-net-emitter-single-file.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/dot-net-emitter.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/dot-net-generator.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/type-link-resolver.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/type-name-simplifier.sysml create mode 100644 docs/sysml2/model/api-mark-dot-net/xml-doc-reader.sysml create mode 100644 docs/sysml2/model/api-mark-msbuild.sysml create mode 100644 docs/sysml2/model/api-mark-msbuild/api-mark-task.sysml create mode 100644 docs/sysml2/model/api-mark-tool.sysml create mode 100644 docs/sysml2/model/api-mark-tool/cli.sysml create mode 100644 docs/sysml2/model/api-mark-tool/cli/context.sysml create mode 100644 docs/sysml2/model/api-mark-tool/program.sysml create mode 100644 docs/sysml2/model/api-mark-tool/self-test.sysml create mode 100644 docs/sysml2/model/api-mark-tool/self-test/validation.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-ast-model.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-ast-parser.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-emitter-gradual-disclosure.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-emitter-single-file.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-emitter.sysml create mode 100644 docs/sysml2/model/api-mark-vhdl/vhdl-generator.sysml create mode 100644 docs/sysml2/model/ots.sysml create mode 100644 docs/sysml2/views/design-views.sysml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 9174c74..384d275 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -71,6 +71,13 @@ "fileassert" ], "rollForward": false + }, + "demaconsulting.sysml2tools.tool": { + "version": "0.1.0-beta.5", + "commands": [ + "sysml2tools" + ], + "rollForward": false } } } diff --git a/.cspell.yaml b/.cspell.yaml index 4832208..487fcb5 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -88,6 +88,7 @@ words: - sonar - sonarmark - subclassable + - sysml - CODEDOC - constexpr - cout diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f8dfe30..f4c8dd3 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -439,7 +439,7 @@ jobs: dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream \ - buildmark versionmark reviewmark fileassert + buildmark versionmark reviewmark fileassert sysml2tools echo "✓ Tool versions captured" # === PREPARE DOCUMENT OUTPUT === @@ -664,6 +664,14 @@ jobs: - name: Create design output directory shell: bash run: mkdir -p docs/design/generated + - name: Render Software Structure diagrams with SysML2Tools + shell: pwsh + run: > + dotnet sysml2tools render + --output docs/design/generated + --format svg + 'docs/sysml2/model/**/*.sysml' + 'docs/sysml2/views/design-views.sysml' - name: Generate Design HTML with Pandoc shell: bash run: > diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 1cc7d46..4614d48 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -7,6 +7,7 @@ needs-review: - '**/*.cs' # All C# source and test files - '**/*.targets' # MSBuild targets files - docs/reqstream/**/*.yaml # Requirements files + - docs/sysml2/**/*.sysml # SysML2 architecture model files - docs/design/**/*.md # Design documentation files - docs/verification/**/*.md # Verification documentation files - docs/user_guide/**/*.md # User guide documentation @@ -37,6 +38,7 @@ reviews: paths: - requirements.yaml - docs/design/introduction.md + - docs/sysml2/**/*.sysml # ApiMarkCore - Specials - id: ApiMark-Core-Architecture diff --git a/.versionmark.yaml b/.versionmark.yaml index 46d904b..61da780 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -71,3 +71,8 @@ tools: sonarmark: command: dotnet tool list regex: (?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?) + + # SysML2Tools (DemaConsulting.SysML2Tools.Tool from dotnet tool list) + sysml2tools: + command: dotnet tool list + regex: (?i)demaconsulting\.sysml2tools\.tool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?) diff --git a/docs/design/api-mark-core.md b/docs/design/api-mark-core.md index 87a9fdc..a210d53 100644 --- a/docs/design/api-mark-core.md +++ b/docs/design/api-mark-core.md @@ -1,5 +1,7 @@ # ApiMarkCore +![ApiMarkCore Structure](generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/emit-config.md b/docs/design/api-mark-core/emit-config.md index d8457be..2fa751c 100644 --- a/docs/design/api-mark-core/emit-config.md +++ b/docs/design/api-mark-core/emit-config.md @@ -1,5 +1,7 @@ ## EmitConfig and OutputFormat +![EmitConfig Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/file-markdown-writer-factory.md b/docs/design/api-mark-core/file-markdown-writer-factory.md index 8f950d9..a93e7dd 100644 --- a/docs/design/api-mark-core/file-markdown-writer-factory.md +++ b/docs/design/api-mark-core/file-markdown-writer-factory.md @@ -1,5 +1,7 @@ ## FileMarkdownWriterFactory +![FileMarkdownWriterFactory Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/file-markdown-writer.md b/docs/design/api-mark-core/file-markdown-writer.md index 907d04a..1a9bdd1 100644 --- a/docs/design/api-mark-core/file-markdown-writer.md +++ b/docs/design/api-mark-core/file-markdown-writer.md @@ -1,5 +1,7 @@ ## FileMarkdownWriter +![FileMarkdownWriter Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/glob-file-collector.md b/docs/design/api-mark-core/glob-file-collector.md index 9997774..dd7989f 100644 --- a/docs/design/api-mark-core/glob-file-collector.md +++ b/docs/design/api-mark-core/glob-file-collector.md @@ -1,5 +1,7 @@ ## GlobFileCollector +![GlobFileCollector Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-api-emitter.md b/docs/design/api-mark-core/i-api-emitter.md index 1e0b2a0..8ec98be 100644 --- a/docs/design/api-mark-core/i-api-emitter.md +++ b/docs/design/api-mark-core/i-api-emitter.md @@ -1,5 +1,7 @@ ## IApiEmitter +![IApiEmitter Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-api-generator.md b/docs/design/api-mark-core/i-api-generator.md index ed69f2a..6e4bebc 100644 --- a/docs/design/api-mark-core/i-api-generator.md +++ b/docs/design/api-mark-core/i-api-generator.md @@ -1,5 +1,7 @@ ## IApiGenerator +![IApiGenerator Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-context.md b/docs/design/api-mark-core/i-context.md index 2c0ae9d..5abff3b 100644 --- a/docs/design/api-mark-core/i-context.md +++ b/docs/design/api-mark-core/i-context.md @@ -1,5 +1,7 @@ ## IContext +![IContext Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-markdown-writer-factory.md b/docs/design/api-mark-core/i-markdown-writer-factory.md index d268882..162222d 100644 --- a/docs/design/api-mark-core/i-markdown-writer-factory.md +++ b/docs/design/api-mark-core/i-markdown-writer-factory.md @@ -1,5 +1,7 @@ ## IMarkdownWriterFactory +![IMarkdownWriterFactory Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-markdown-writer.md b/docs/design/api-mark-core/i-markdown-writer.md index 5e08fc8..a11d9da 100644 --- a/docs/design/api-mark-core/i-markdown-writer.md +++ b/docs/design/api-mark-core/i-markdown-writer.md @@ -1,5 +1,7 @@ ## IMarkdownWriter +![IMarkdownWriter Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/path-helpers.md b/docs/design/api-mark-core/path-helpers.md index 22c4152..86a882f 100644 --- a/docs/design/api-mark-core/path-helpers.md +++ b/docs/design/api-mark-core/path-helpers.md @@ -1,5 +1,7 @@ ## PathHelpers +![PathHelpers Structure](../generated/ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-cpp.md b/docs/design/api-mark-cpp.md index 9855789..1680dc7 100644 --- a/docs/design/api-mark-cpp.md +++ b/docs/design/api-mark-cpp.md @@ -1,5 +1,7 @@ # ApiMarkCpp +![ApiMarkCpp Structure](generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/clang-ast-parser.md b/docs/design/api-mark-cpp/clang-ast-parser.md index caa030e..a293415 100644 --- a/docs/design/api-mark-cpp/clang-ast-parser.md +++ b/docs/design/api-mark-cpp/clang-ast-parser.md @@ -1,5 +1,7 @@ ## ClangAstParser +![ClangAstParser Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-ast-model.md b/docs/design/api-mark-cpp/cpp-ast-model.md index 041932f..07a583f 100644 --- a/docs/design/api-mark-cpp/cpp-ast-model.md +++ b/docs/design/api-mark-cpp/cpp-ast-model.md @@ -1,5 +1,7 @@ ## CppAstModel +![CppAstModel Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md b/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md index f6efee6..f673470 100644 --- a/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md @@ -1,5 +1,7 @@ ## CppEmitterGradualDisclosure +![CppEmitterGradualDisclosure Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-emitter-single-file.md b/docs/design/api-mark-cpp/cpp-emitter-single-file.md index e42fe2f..63e59b0 100644 --- a/docs/design/api-mark-cpp/cpp-emitter-single-file.md +++ b/docs/design/api-mark-cpp/cpp-emitter-single-file.md @@ -1,5 +1,7 @@ ## CppEmitterSingleFile +![CppEmitterSingleFile Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-emitter.md b/docs/design/api-mark-cpp/cpp-emitter.md index 99c05eb..e233c9e 100644 --- a/docs/design/api-mark-cpp/cpp-emitter.md +++ b/docs/design/api-mark-cpp/cpp-emitter.md @@ -1,5 +1,7 @@ ## CppEmitter +![CppEmitter Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-generator.md b/docs/design/api-mark-cpp/cpp-generator.md index 8f63a90..74d6135 100644 --- a/docs/design/api-mark-cpp/cpp-generator.md +++ b/docs/design/api-mark-cpp/cpp-generator.md @@ -1,5 +1,7 @@ ## CppGenerator +![CppGenerator Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-type-link-resolver.md b/docs/design/api-mark-cpp/cpp-type-link-resolver.md index 72a9392..45b1717 100644 --- a/docs/design/api-mark-cpp/cpp-type-link-resolver.md +++ b/docs/design/api-mark-cpp/cpp-type-link-resolver.md @@ -1,5 +1,7 @@ ## CppTypeLinkResolver +![CppTypeLinkResolver Structure](../generated/ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-dot-net.md b/docs/design/api-mark-dot-net.md index 79b0770..7c0305c 100644 --- a/docs/design/api-mark-dot-net.md +++ b/docs/design/api-mark-dot-net.md @@ -1,5 +1,7 @@ # ApiMarkDotNet +![ApiMarkDotNet Structure](generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/dot-net-ast-model.md b/docs/design/api-mark-dot-net/dot-net-ast-model.md index 726d5a1..b7e61ed 100644 --- a/docs/design/api-mark-dot-net/dot-net-ast-model.md +++ b/docs/design/api-mark-dot-net/dot-net-ast-model.md @@ -1,5 +1,7 @@ ## DotNetAstModel +![DotNetAstModel Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md b/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md index 7b8f1e5..6c0e2a3 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md @@ -1,5 +1,7 @@ ## DotNetEmitterGradualDisclosure +![DotNetEmitterGradualDisclosure Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md b/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md index 0a6f589..587a527 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md @@ -1,5 +1,7 @@ ## DotNetEmitterSingleFile +![DotNetEmitterSingleFile Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/dot-net-emitter.md b/docs/design/api-mark-dot-net/dot-net-emitter.md index 62049f8..f8c2c2f 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter.md @@ -1,5 +1,7 @@ ## DotNetEmitter +![DotNetEmitter Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/dot-net-generator.md b/docs/design/api-mark-dot-net/dot-net-generator.md index 1dfd05e..8b00ae4 100644 --- a/docs/design/api-mark-dot-net/dot-net-generator.md +++ b/docs/design/api-mark-dot-net/dot-net-generator.md @@ -1,5 +1,7 @@ ## DotNetGenerator +![DotNetGenerator Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/type-link-resolver.md b/docs/design/api-mark-dot-net/type-link-resolver.md index b3e1deb..26605af 100644 --- a/docs/design/api-mark-dot-net/type-link-resolver.md +++ b/docs/design/api-mark-dot-net/type-link-resolver.md @@ -1,5 +1,7 @@ ## TypeLinkResolver +![TypeLinkResolver Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/type-name-simplifier.md b/docs/design/api-mark-dot-net/type-name-simplifier.md index 92d2af0..c424c1b 100644 --- a/docs/design/api-mark-dot-net/type-name-simplifier.md +++ b/docs/design/api-mark-dot-net/type-name-simplifier.md @@ -1,5 +1,7 @@ ## TypeNameSimplifier +![TypeNameSimplifier Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-dot-net/xml-doc-reader.md b/docs/design/api-mark-dot-net/xml-doc-reader.md index 98f5a8f..43517a5 100644 --- a/docs/design/api-mark-dot-net/xml-doc-reader.md +++ b/docs/design/api-mark-dot-net/xml-doc-reader.md @@ -1,5 +1,7 @@ ## XmlDocReader +![XmlDocReader Structure](../generated/ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-msbuild.md b/docs/design/api-mark-msbuild.md index ca0d84d..562a955 100644 --- a/docs/design/api-mark-msbuild.md +++ b/docs/design/api-mark-msbuild.md @@ -1,5 +1,7 @@ # ApiMarkMsbuild +![ApiMarkMsbuild Structure](generated/ApiMarkMsbuildView.svg) + diff --git a/docs/design/api-mark-msbuild/api-mark-task.md b/docs/design/api-mark-msbuild/api-mark-task.md index 5dcfe54..55c4052 100644 --- a/docs/design/api-mark-msbuild/api-mark-task.md +++ b/docs/design/api-mark-msbuild/api-mark-task.md @@ -1,5 +1,7 @@ ## ApiMarkTask +![ApiMarkTask Structure](../generated/ApiMarkMsbuildView.svg) + diff --git a/docs/design/api-mark-tool.md b/docs/design/api-mark-tool.md index 28e26c8..5c5321d 100644 --- a/docs/design/api-mark-tool.md +++ b/docs/design/api-mark-tool.md @@ -1,5 +1,7 @@ # ApiMarkTool +![ApiMarkTool Structure](generated/ApiMarkToolView.svg) + diff --git a/docs/design/api-mark-tool/cli.md b/docs/design/api-mark-tool/cli.md index 22121ea..260e23a 100644 --- a/docs/design/api-mark-tool/cli.md +++ b/docs/design/api-mark-tool/cli.md @@ -1,5 +1,7 @@ ## Cli +![Cli Structure](../generated/CliView.svg) + diff --git a/docs/design/api-mark-tool/cli/context.md b/docs/design/api-mark-tool/cli/context.md index 7511e91..0111e46 100644 --- a/docs/design/api-mark-tool/cli/context.md +++ b/docs/design/api-mark-tool/cli/context.md @@ -1,5 +1,7 @@ ### Context +![Context Structure](../../generated/CliView.svg) + diff --git a/docs/design/api-mark-tool/program.md b/docs/design/api-mark-tool/program.md index 04a78e6..6d5102e 100644 --- a/docs/design/api-mark-tool/program.md +++ b/docs/design/api-mark-tool/program.md @@ -1,5 +1,7 @@ ## Program +![Program Structure](../generated/ApiMarkToolView.svg) + diff --git a/docs/design/api-mark-tool/self-test.md b/docs/design/api-mark-tool/self-test.md index 8f10fc6..7027891 100644 --- a/docs/design/api-mark-tool/self-test.md +++ b/docs/design/api-mark-tool/self-test.md @@ -1,5 +1,7 @@ ## SelfTest +![SelfTest Structure](../generated/SelfTestView.svg) + diff --git a/docs/design/api-mark-tool/self-test/validation.md b/docs/design/api-mark-tool/self-test/validation.md index c2236a6..d698259 100644 --- a/docs/design/api-mark-tool/self-test/validation.md +++ b/docs/design/api-mark-tool/self-test/validation.md @@ -1,5 +1,7 @@ ### Validation +![Validation Structure](../../generated/SelfTestView.svg) + diff --git a/docs/design/api-mark-vhdl.md b/docs/design/api-mark-vhdl.md index 0840cdb..5d13d72 100644 --- a/docs/design/api-mark-vhdl.md +++ b/docs/design/api-mark-vhdl.md @@ -1,5 +1,7 @@ # ApiMarkVhdl +![ApiMarkVhdl Structure](generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-ast-model.md b/docs/design/api-mark-vhdl/vhdl-ast-model.md index a3e285b..c87bd93 100644 --- a/docs/design/api-mark-vhdl/vhdl-ast-model.md +++ b/docs/design/api-mark-vhdl/vhdl-ast-model.md @@ -1,5 +1,7 @@ ## VhdlAstModel +![VhdlAstModel Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-ast-parser.md b/docs/design/api-mark-vhdl/vhdl-ast-parser.md index 0824795..13db2cb 100644 --- a/docs/design/api-mark-vhdl/vhdl-ast-parser.md +++ b/docs/design/api-mark-vhdl/vhdl-ast-parser.md @@ -1,5 +1,7 @@ ## VhdlAstParser +![VhdlAstParser Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md b/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md index 7223048..9d951da 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md @@ -1,5 +1,7 @@ ## VhdlEmitterGradualDisclosure +![VhdlEmitterGradualDisclosure Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md b/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md index 31e06ae..01727da 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md @@ -1,5 +1,7 @@ ## VhdlEmitterSingleFile +![VhdlEmitterSingleFile Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-emitter.md b/docs/design/api-mark-vhdl/vhdl-emitter.md index 0bf6532..9674b9c 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter.md @@ -1,5 +1,7 @@ ## VhdlEmitter +![VhdlEmitter Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-generator.md b/docs/design/api-mark-vhdl/vhdl-generator.md index 46a96a7..ca75bb8 100644 --- a/docs/design/api-mark-vhdl/vhdl-generator.md +++ b/docs/design/api-mark-vhdl/vhdl-generator.md @@ -1,5 +1,7 @@ ## VhdlGenerator +![VhdlGenerator Structure](../generated/ApiMarkVhdlView.svg) + diff --git a/docs/design/introduction.md b/docs/design/introduction.md index cbbba69..8f9ae75 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -1,5 +1,7 @@ # Introduction +![Software Structure](generated/SoftwareStructureView.svg) + ApiMark generates compact, AI-friendly API reference documentation in Markdown from source code and its associated metadata (XML doc comments, header files, docstrings, etc.). The output is designed for gradual disclosure: an AI can read a lightweight diff --git a/docs/sysml2/model/api-mark-core.sysml b/docs/sysml2/model/api-mark-core.sysml new file mode 100644 index 0000000..f1c5e9c --- /dev/null +++ b/docs/sysml2/model/api-mark-core.sysml @@ -0,0 +1,28 @@ +package ApiMarkCore { + import OtsDependencies::*; + + doc + /* + * ApiMarkCore is a shared-contracts system. It defines the interfaces, output configuration, and Markdown writer helpers shared by all language generators. + */ + + part def ApiMarkCoreSystem { + doc /* The ApiMarkCore system as a whole. */ + + comment designRef /* Design: docs/design/api-mark-core.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core.yaml */ + + part iApiGenerator : IApiGenerator; + part iApiEmitter : IApiEmitter; + part emitConfig : EmitConfig; + part iContext : IContext; + part iMarkdownWriterFactory : IMarkdownWriterFactory; + part fileMarkdownWriterFactory : FileMarkdownWriterFactory; + part iMarkdownWriter : IMarkdownWriter; + part fileMarkdownWriter : FileMarkdownWriter; + part pathHelpers : PathHelpers; + part globFileCollector : GlobFileCollector; + part fileSystemGlobbing : FileSystemGlobbing; + } +} diff --git a/docs/sysml2/model/api-mark-core/emit-config.sysml b/docs/sysml2/model/api-mark-core/emit-config.sysml new file mode 100644 index 0000000..151bd29 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/emit-config.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def EmitConfig { + doc /* EmitConfig and OutputFormat together define the shared output-configuration contract passed to every emitter. */ + + comment sourceRef /* Source: src/ApiMark.Core/EmitConfig.cs, src/ApiMark.Core/OutputFormat.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/EmitConfigTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/emit-config.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/emit-config.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/emit-config.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/file-markdown-writer-factory.sysml b/docs/sysml2/model/api-mark-core/file-markdown-writer-factory.sysml new file mode 100644 index 0000000..01694a7 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/file-markdown-writer-factory.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def FileMarkdownWriterFactory { + doc /* FileMarkdownWriterFactory is the production file-system implementation of IMarkdownWriterFactory. */ + + comment sourceRef /* Source: src/ApiMark.Core/FileMarkdownWriterFactory.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/FileMarkdownWriterFactoryTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/file-markdown-writer-factory.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/file-markdown-writer-factory.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/file-markdown-writer-factory.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/file-markdown-writer.sysml b/docs/sysml2/model/api-mark-core/file-markdown-writer.sysml new file mode 100644 index 0000000..1be664d --- /dev/null +++ b/docs/sysml2/model/api-mark-core/file-markdown-writer.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def FileMarkdownWriter { + doc /* FileMarkdownWriter is the production file-system implementation of IMarkdownWriter. */ + + comment sourceRef /* Source: src/ApiMark.Core/FileMarkdownWriter.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/FileMarkdownWriterTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/file-markdown-writer.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/file-markdown-writer.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/file-markdown-writer.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/glob-file-collector.sysml b/docs/sysml2/model/api-mark-core/glob-file-collector.sysml new file mode 100644 index 0000000..d749386 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/glob-file-collector.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def GlobFileCollector { + doc /* GlobFileCollector is a stateless utility that discovers source files from glob patterns for filesystem-based generators. */ + + comment sourceRef /* Source: src/ApiMark.Core/GlobFileCollector.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/GlobFileCollectorTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/glob-file-collector.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/glob-file-collector.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/glob-file-collector.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/i-api-emitter.sysml b/docs/sysml2/model/api-mark-core/i-api-emitter.sysml new file mode 100644 index 0000000..ef434e5 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/i-api-emitter.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def IApiEmitter { + doc /* IApiEmitter is the second stage of the two-stage generation pipeline: it writes Markdown output from a parsed AST model. */ + + comment sourceRef /* Source: src/ApiMark.Core/IApiEmitter.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/IApiEmitterTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/i-api-emitter.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/i-api-emitter.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/i-api-emitter.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/i-api-generator.sysml b/docs/sysml2/model/api-mark-core/i-api-generator.sysml new file mode 100644 index 0000000..3b875c0 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/i-api-generator.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def IApiGenerator { + doc /* IApiGenerator is the first stage of the two-stage generation pipeline: it parses source input into a language AST model. */ + + comment sourceRef /* Source: src/ApiMark.Core/IApiGenerator.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/IApiGeneratorTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/i-api-generator.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/i-api-generator.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/i-api-generator.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/i-context.sysml b/docs/sysml2/model/api-mark-core/i-context.sysml new file mode 100644 index 0000000..50a62ac --- /dev/null +++ b/docs/sysml2/model/api-mark-core/i-context.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def IContext { + doc /* IContext is the minimal output channel that language generators use to emit Markdown writers and diagnostics. */ + + comment sourceRef /* Source: src/ApiMark.Core/IContext.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/IContextTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/i-context.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/i-context.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/i-context.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/i-markdown-writer-factory.sysml b/docs/sysml2/model/api-mark-core/i-markdown-writer-factory.sysml new file mode 100644 index 0000000..31d6705 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/i-markdown-writer-factory.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def IMarkdownWriterFactory { + doc /* IMarkdownWriterFactory is the factory contract for creating IMarkdownWriter instances rooted at an output directory. */ + + comment sourceRef /* Source: src/ApiMark.Core/IMarkdownWriterFactory.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/IMarkdownWriterFactoryTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/i-markdown-writer-factory.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/i-markdown-writer-factory.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/i-markdown-writer-factory.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/i-markdown-writer.sysml b/docs/sysml2/model/api-mark-core/i-markdown-writer.sysml new file mode 100644 index 0000000..9f32e5f --- /dev/null +++ b/docs/sysml2/model/api-mark-core/i-markdown-writer.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def IMarkdownWriter { + doc /* IMarkdownWriter is the per-file Markdown writing contract obtained from an IMarkdownWriterFactory. */ + + comment sourceRef /* Source: src/ApiMark.Core/IMarkdownWriter.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/IMarkdownWriterTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/i-markdown-writer.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/i-markdown-writer.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/i-markdown-writer.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-core/path-helpers.sysml b/docs/sysml2/model/api-mark-core/path-helpers.sysml new file mode 100644 index 0000000..0e5db30 --- /dev/null +++ b/docs/sysml2/model/api-mark-core/path-helpers.sysml @@ -0,0 +1,11 @@ +package ApiMarkCore { + part def PathHelpers { + doc /* PathHelpers is the single, auditable point of path-safety enforcement for combining and validating output paths. */ + + comment sourceRef /* Source: src/ApiMark.Core/PathHelpers.cs */ + comment testRef /* Test: test/ApiMark.Core.Tests/PathHelpersTests.cs */ + comment designRef /* Design: docs/design/api-mark-core/path-helpers.md */ + comment verificationRef /* Verification: docs/verification/api-mark-core/path-helpers.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-core/path-helpers.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp.sysml b/docs/sysml2/model/api-mark-cpp.sysml new file mode 100644 index 0000000..45504de --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp.sysml @@ -0,0 +1,25 @@ +package ApiMarkCpp { + import OtsDependencies::*; + + doc + /* + * ApiMarkCpp provides C++ language support by parsing selected public headers with clang and emitting gradual-disclosure Markdown documentation. + */ + + part def ApiMarkCppSystem { + doc /* The ApiMarkCpp system as a whole. */ + + comment designRef /* Design: docs/design/api-mark-cpp.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp.yaml */ + + part cppGenerator : CppGenerator; + part cppAstModel : CppAstModel; + part clangAstParser : ClangAstParser; + part cppEmitter : CppEmitter; + part cppEmitterGradualDisclosure : CppEmitterGradualDisclosure; + part cppEmitterSingleFile : CppEmitterSingleFile; + part cppTypeLinkResolver : CppTypeLinkResolver; + part clang : Clang; + } +} diff --git a/docs/sysml2/model/api-mark-cpp/clang-ast-parser.sysml b/docs/sysml2/model/api-mark-cpp/clang-ast-parser.sysml new file mode 100644 index 0000000..70d23bc --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/clang-ast-parser.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def ClangAstParser { + doc /* ClangAstParser is the internal C++ parsing unit used by CppGenerator; it invokes clang and builds the AST model from its JSON output. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppAst/ClangAstParser.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/ClangAstParserTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/clang-ast-parser.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/clang-ast-parser.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/clang-ast-parser.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-ast-model.sysml b/docs/sysml2/model/api-mark-cpp/cpp-ast-model.sysml new file mode 100644 index 0000000..9a2eef4 --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-ast-model.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppAstModel { + doc /* CppAstModel defines the immutable record types that represent the parsed C++ AST. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppAst/CppAstModel.cs, src/ApiMark.Cpp/CppExternalTypeInfo.cs, src/ApiMark.Cpp/ApiVisibility.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppAstModelTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-ast-model.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-ast-model.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-ast-model.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-emitter-gradual-disclosure.sysml b/docs/sysml2/model/api-mark-cpp/cpp-emitter-gradual-disclosure.sysml new file mode 100644 index 0000000..060b943 --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-emitter-gradual-disclosure.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppEmitterGradualDisclosure { + doc /* CppEmitterGradualDisclosure writes the multi-file Markdown layout for C++ API documentation. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppEmitterGradualDisclosure.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppEmitterGradualDisclosureTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-emitter-gradual-disclosure.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-emitter-gradual-disclosure.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-emitter-single-file.sysml b/docs/sysml2/model/api-mark-cpp/cpp-emitter-single-file.sysml new file mode 100644 index 0000000..31caccf --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-emitter-single-file.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppEmitterSingleFile { + doc /* CppEmitterSingleFile writes all C++ API documentation into a single Markdown file. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppEmitterSingleFile.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppEmitterSingleFileTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-emitter-single-file.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-emitter-single-file.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-emitter-single-file.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-emitter.sysml b/docs/sysml2/model/api-mark-cpp/cpp-emitter.sysml new file mode 100644 index 0000000..5d2fe78 --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-emitter.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppEmitter { + doc /* CppEmitter implements IApiEmitter for C++ documentation, storing the parsed AST and dispatching to an emit strategy. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppEmitter.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppEmitterTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-emitter.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-emitter.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-emitter.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-generator.sysml b/docs/sysml2/model/api-mark-cpp/cpp-generator.sysml new file mode 100644 index 0000000..bfc9a7c --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-generator.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppGenerator { + doc /* CppGenerator implements IApiGenerator for C++ libraries, collecting public headers and invoking clang to parse them. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppGenerator.cs, src/ApiMark.Cpp/CppGeneratorOptions.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppGeneratorTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-generator.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-generator.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-generator.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-cpp/cpp-type-link-resolver.sysml b/docs/sysml2/model/api-mark-cpp/cpp-type-link-resolver.sysml new file mode 100644 index 0000000..bc7ea52 --- /dev/null +++ b/docs/sysml2/model/api-mark-cpp/cpp-type-link-resolver.sysml @@ -0,0 +1,11 @@ +package ApiMarkCpp { + part def CppTypeLinkResolver { + doc /* CppTypeLinkResolver resolves simplified C++ type strings to Markdown table-cell link targets. */ + + comment sourceRef /* Source: src/ApiMark.Cpp/CppTypeLinkResolver.cs */ + comment testRef /* Test: test/ApiMark.Cpp.Tests/CppTypeLinkResolverTests.cs */ + comment designRef /* Design: docs/design/api-mark-cpp/cpp-type-link-resolver.md */ + comment verificationRef /* Verification: docs/verification/api-mark-cpp/cpp-type-link-resolver.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-cpp/cpp-type-link-resolver.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net.sysml b/docs/sysml2/model/api-mark-dot-net.sysml new file mode 100644 index 0000000..f257e85 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net.sysml @@ -0,0 +1,26 @@ +package ApiMarkDotNet { + import OtsDependencies::*; + + doc + /* + * ApiMarkDotNet provides C#/.NET language support by reading a compiled .NET assembly with Mono.Cecil and emitting gradual-disclosure Markdown documentation. + */ + + part def ApiMarkDotNetSystem { + doc /* The ApiMarkDotNet system as a whole. */ + + comment designRef /* Design: docs/design/api-mark-dot-net.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net.yaml */ + + part dotNetGenerator : DotNetGenerator; + part dotNetAstModel : DotNetAstModel; + part dotNetEmitter : DotNetEmitter; + part dotNetEmitterGradualDisclosure : DotNetEmitterGradualDisclosure; + part dotNetEmitterSingleFile : DotNetEmitterSingleFile; + part typeLinkResolver : TypeLinkResolver; + part xmlDocReader : XmlDocReader; + part typeNameSimplifier : TypeNameSimplifier; + part monoCecil : MonoCecil; + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/dot-net-ast-model.sysml b/docs/sysml2/model/api-mark-dot-net/dot-net-ast-model.sysml new file mode 100644 index 0000000..8684936 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/dot-net-ast-model.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def DotNetAstModel { + doc /* DotNetAstModel is an immutable data class holding all parsed .NET assembly metadata. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/DotNetAstModel.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/DotNetAstModelTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/dot-net-ast-model.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/dot-net-ast-model.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/dot-net-ast-model.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-gradual-disclosure.sysml b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-gradual-disclosure.sysml new file mode 100644 index 0000000..050c2af --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-gradual-disclosure.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def DotNetEmitterGradualDisclosure { + doc /* DotNetEmitterGradualDisclosure writes the complete gradual-disclosure Markdown layout for .NET API documentation. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/DotNetEmitterGradualDisclosure.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/DotNetEmitterGradualDisclosureTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/dot-net-emitter-gradual-disclosure.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-single-file.sysml b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-single-file.sysml new file mode 100644 index 0000000..b0424c2 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter-single-file.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def DotNetEmitterSingleFile { + doc /* DotNetEmitterSingleFile writes all .NET API documentation into a single Markdown file. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/DotNetEmitterSingleFile.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/DotNetEmitterSingleFileTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/dot-net-emitter-single-file.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/dot-net-emitter-single-file.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/dot-net-emitter-single-file.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/dot-net-emitter.sysml b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter.sysml new file mode 100644 index 0000000..1d12b86 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/dot-net-emitter.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def DotNetEmitter { + doc /* DotNetEmitter implements IApiEmitter and dispatches between the gradual-disclosure and single-file emitters. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/DotNetEmitter.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/DotNetEmitterTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/dot-net-emitter.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/dot-net-emitter.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/dot-net-emitter.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/dot-net-generator.sysml b/docs/sysml2/model/api-mark-dot-net/dot-net-generator.sysml new file mode 100644 index 0000000..d5b1ed4 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/dot-net-generator.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def DotNetGenerator { + doc /* DotNetGenerator implements IApiGenerator for C#/.NET assemblies, reading a compiled assembly with Mono.Cecil. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/DotNetGenerator.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/DotNetGeneratorTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/dot-net-generator.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/dot-net-generator.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/dot-net-generator.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/type-link-resolver.sysml b/docs/sysml2/model/api-mark-dot-net/type-link-resolver.sysml new file mode 100644 index 0000000..405edb2 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/type-link-resolver.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def TypeLinkResolver { + doc /* TypeLinkResolver resolves Mono.Cecil TypeReference instances to Markdown link targets. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/TypeLinkResolver.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/TypeLinkResolverTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/type-link-resolver.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/type-link-resolver.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/type-link-resolver.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/type-name-simplifier.sysml b/docs/sysml2/model/api-mark-dot-net/type-name-simplifier.sysml new file mode 100644 index 0000000..c43e2a4 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/type-name-simplifier.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def TypeNameSimplifier { + doc /* TypeNameSimplifier converts Mono.Cecil type references into idiomatic, readable C# type names. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/TypeNameSimplifier.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/TypeNameSimplifierTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/type-name-simplifier.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/type-name-simplifier.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/type-name-simplifier.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-dot-net/xml-doc-reader.sysml b/docs/sysml2/model/api-mark-dot-net/xml-doc-reader.sysml new file mode 100644 index 0000000..a0281d5 --- /dev/null +++ b/docs/sysml2/model/api-mark-dot-net/xml-doc-reader.sysml @@ -0,0 +1,11 @@ +package ApiMarkDotNet { + part def XmlDocReader { + doc /* XmlDocReader reads and indexes a .NET XML documentation file for fast lookup of member documentation. */ + + comment sourceRef /* Source: src/ApiMark.DotNet/XmlDocReader.cs */ + comment testRef /* Test: test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs */ + comment designRef /* Design: docs/design/api-mark-dot-net/xml-doc-reader.md */ + comment verificationRef /* Verification: docs/verification/api-mark-dot-net/xml-doc-reader.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-msbuild.sysml b/docs/sysml2/model/api-mark-msbuild.sysml new file mode 100644 index 0000000..34384df --- /dev/null +++ b/docs/sysml2/model/api-mark-msbuild.sysml @@ -0,0 +1,17 @@ +package ApiMarkMsbuild { + doc + /* + * ApiMarkMsbuild is a single-unit system containing the ApiMarkTask unit; it wraps ApiMarkTool as an MSBuild task. + */ + + part def ApiMarkMsbuildSystem { + doc /* The ApiMarkMsbuild system as a whole. */ + + comment testRef /* Test: test/ApiMark.MSBuild.PackageTests/PackageIntegrationTests.cs */ + comment designRef /* Design: docs/design/api-mark-msbuild.md */ + comment verificationRef /* Verification: docs/verification/api-mark-msbuild.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-msbuild.yaml */ + + part apiMarkTask : ApiMarkTask; + } +} diff --git a/docs/sysml2/model/api-mark-msbuild/api-mark-task.sysml b/docs/sysml2/model/api-mark-msbuild/api-mark-task.sysml new file mode 100644 index 0000000..779aff2 --- /dev/null +++ b/docs/sysml2/model/api-mark-msbuild/api-mark-task.sysml @@ -0,0 +1,11 @@ +package ApiMarkMsbuild { + part def ApiMarkTask { + doc /* ApiMarkTask is the MSBuild task entry point for ApiMarkMsbuild; it fires ApiMarkTool out-of-process and reports results back to MSBuild. */ + + comment sourceRef /* Source: src/ApiMark.MSBuild/ApiMarkTask.cs */ + comment testRef /* Test: test/ApiMark.MSBuild.Tests/ApiMarkTaskTests.cs */ + comment designRef /* Design: docs/design/api-mark-msbuild/api-mark-task.md */ + comment verificationRef /* Verification: docs/verification/api-mark-msbuild/api-mark-task.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-msbuild/api-mark-task.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-tool.sysml b/docs/sysml2/model/api-mark-tool.sysml new file mode 100644 index 0000000..b019614 --- /dev/null +++ b/docs/sysml2/model/api-mark-tool.sysml @@ -0,0 +1,18 @@ +package ApiMarkTool { + doc + /* + * ApiMarkTool is organized into two subsystems (Cli and SelfTest) and one top-level unit (Program); it is the .NET executable invoked by ApiMarkTask and directly by users or CI pipelines. + */ + + part def ApiMarkToolSystem { + doc /* The ApiMarkTool system as a whole. */ + + comment designRef /* Design: docs/design/api-mark-tool.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool.yaml */ + + part program : Program; + part cli : CliSubsystem; + part selfTest : SelfTestSubsystem; + } +} diff --git a/docs/sysml2/model/api-mark-tool/cli.sysml b/docs/sysml2/model/api-mark-tool/cli.sysml new file mode 100644 index 0000000..250a427 --- /dev/null +++ b/docs/sysml2/model/api-mark-tool/cli.sysml @@ -0,0 +1,11 @@ +package ApiMarkTool { + part def CliSubsystem { + doc /* Cli subsystem: command-line argument parsing and I/O ownership for ApiMarkTool. */ + + comment designRef /* Design: docs/design/api-mark-tool/cli.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool/cli.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool/cli.yaml */ + + part context : Context; + } +} diff --git a/docs/sysml2/model/api-mark-tool/cli/context.sysml b/docs/sysml2/model/api-mark-tool/cli/context.sysml new file mode 100644 index 0000000..1aa6ebb --- /dev/null +++ b/docs/sysml2/model/api-mark-tool/cli/context.sysml @@ -0,0 +1,11 @@ +package ApiMarkTool { + part def Context { + doc /* Context is the command-line argument parser and output router for ApiMarkTool. */ + + comment sourceRef /* Source: src/ApiMark.Tool/Cli/Context.cs */ + comment testRef /* Test: test/ApiMark.Tool.Tests/Cli/ContextTests.cs */ + comment designRef /* Design: docs/design/api-mark-tool/cli/context.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool/cli/context.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool/cli/context.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-tool/program.sysml b/docs/sysml2/model/api-mark-tool/program.sysml new file mode 100644 index 0000000..0cef1d3 --- /dev/null +++ b/docs/sysml2/model/api-mark-tool/program.sysml @@ -0,0 +1,11 @@ +package ApiMarkTool { + part def Program { + doc /* Program is the CLI entry point for ApiMarkTool; it parses command-line arguments and dispatches to the Cli and SelfTest subsystems. */ + + comment sourceRef /* Source: src/ApiMark.Tool/Program.cs */ + comment testRef /* Test: test/ApiMark.Tool.Tests/ProgramTests.cs */ + comment designRef /* Design: docs/design/api-mark-tool/program.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool/program.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool/program.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-tool/self-test.sysml b/docs/sysml2/model/api-mark-tool/self-test.sysml new file mode 100644 index 0000000..8292582 --- /dev/null +++ b/docs/sysml2/model/api-mark-tool/self-test.sysml @@ -0,0 +1,14 @@ +package ApiMarkTool { + import OtsDependencies::*; + + part def SelfTestSubsystem { + doc /* SelfTest subsystem: runs in-process self-validation tests to verify core ApiMarkTool functionality. */ + + comment designRef /* Design: docs/design/api-mark-tool/self-test.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool/self-test.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool/self-test.yaml */ + + part validation : Validation; + part testResults : TestResults; + } +} diff --git a/docs/sysml2/model/api-mark-tool/self-test/validation.sysml b/docs/sysml2/model/api-mark-tool/self-test/validation.sysml new file mode 100644 index 0000000..773ca9e --- /dev/null +++ b/docs/sysml2/model/api-mark-tool/self-test/validation.sysml @@ -0,0 +1,11 @@ +package ApiMarkTool { + part def Validation { + doc /* Validation runs in-process self-tests that confirm core ApiMarkTool functionality and reports results via DemaConsulting.TestResults. */ + + comment sourceRef /* Source: src/ApiMark.Tool/SelfTest/Validation.cs */ + comment testRef /* Test: test/ApiMark.Tool.Tests/SelfTest/ValidationTests.cs */ + comment designRef /* Design: docs/design/api-mark-tool/self-test/validation.md */ + comment verificationRef /* Verification: docs/verification/api-mark-tool/self-test/validation.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-tool/self-test/validation.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl.sysml b/docs/sysml2/model/api-mark-vhdl.sysml new file mode 100644 index 0000000..0472c1a --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl.sysml @@ -0,0 +1,24 @@ +package ApiMarkVhdl { + import OtsDependencies::*; + + doc + /* + * ApiMarkVhdl provides VHDL language support by parsing VHDL source files with an ANTLR4 grammar and emitting Markdown documentation. + */ + + part def ApiMarkVhdlSystem { + doc /* The ApiMarkVhdl system as a whole. */ + + comment designRef /* Design: docs/design/api-mark-vhdl.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl.yaml */ + + part vhdlGenerator : VhdlGenerator; + part vhdlAstModel : VhdlAstModel; + part vhdlAstParser : VhdlAstParser; + part vhdlEmitter : VhdlEmitter; + part vhdlEmitterGradualDisclosure : VhdlEmitterGradualDisclosure; + part vhdlEmitterSingleFile : VhdlEmitterSingleFile; + part antlr4RuntimeStandard : Antlr4RuntimeStandard; + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-ast-model.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-ast-model.sysml new file mode 100644 index 0000000..d5959af --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-ast-model.sysml @@ -0,0 +1,10 @@ +package ApiMarkVhdl { + part def VhdlAstModel { + doc /* VhdlAstModel defines the immutable record types that represent the parsed result of a VHDL source file. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlAst/VhdlAstModel.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-ast-model.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-ast-model.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-ast-model.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-ast-parser.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-ast-parser.sysml new file mode 100644 index 0000000..5e6c70b --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-ast-parser.sysml @@ -0,0 +1,11 @@ +package ApiMarkVhdl { + part def VhdlAstParser { + doc /* VhdlAstParser reads a VHDL source file, pre-processes doc comments, and drives the ANTLR4 vhdl2008 grammar. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlAst/VhdlAstParser.cs */ + comment testRef /* Test: test/ApiMark.Vhdl.Tests/VhdlAstParserTests.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-ast-parser.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-ast-parser.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-ast-parser.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-gradual-disclosure.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-gradual-disclosure.sysml new file mode 100644 index 0000000..8eb593c --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-gradual-disclosure.sysml @@ -0,0 +1,11 @@ +package ApiMarkVhdl { + part def VhdlEmitterGradualDisclosure { + doc /* VhdlEmitterGradualDisclosure writes one Markdown file per VHDL entity and an index for gradual disclosure. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlEmitterGradualDisclosure.cs */ + comment testRef /* Test: test/ApiMark.Vhdl.Tests/VhdlEmitterGradualDisclosureTests.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-emitter-gradual-disclosure.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-single-file.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-single-file.sysml new file mode 100644 index 0000000..3261ee5 --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter-single-file.sysml @@ -0,0 +1,11 @@ +package ApiMarkVhdl { + part def VhdlEmitterSingleFile { + doc /* VhdlEmitterSingleFile writes all VHDL API documentation into a single api.md file. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlEmitterSingleFile.cs */ + comment testRef /* Test: test/ApiMark.Vhdl.Tests/VhdlEmitterSingleFileTests.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-emitter-single-file.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-emitter-single-file.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-emitter-single-file.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-emitter.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter.sysml new file mode 100644 index 0000000..917593b --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-emitter.sysml @@ -0,0 +1,11 @@ +package ApiMarkVhdl { + part def VhdlEmitter { + doc /* VhdlEmitter implements IApiEmitter, validates emitter arguments, and dispatches to an emit strategy for VHDL documentation. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlEmitter.cs */ + comment testRef /* Test: test/ApiMark.Vhdl.Tests/VhdlEmitterTests.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-emitter.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-emitter.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-emitter.yaml */ + } +} diff --git a/docs/sysml2/model/api-mark-vhdl/vhdl-generator.sysml b/docs/sysml2/model/api-mark-vhdl/vhdl-generator.sysml new file mode 100644 index 0000000..1c8c4c2 --- /dev/null +++ b/docs/sysml2/model/api-mark-vhdl/vhdl-generator.sysml @@ -0,0 +1,11 @@ +package ApiMarkVhdl { + part def VhdlGenerator { + doc /* VhdlGenerator is the public entry point for VHDL API documentation generation. */ + + comment sourceRef /* Source: src/ApiMark.Vhdl/VhdlGenerator.cs, src/ApiMark.Vhdl/VhdlGeneratorOptions.cs */ + comment testRef /* Test: test/ApiMark.Vhdl.Tests/VhdlGeneratorTests.cs */ + comment designRef /* Design: docs/design/api-mark-vhdl/vhdl-generator.md */ + comment verificationRef /* Verification: docs/verification/api-mark-vhdl/vhdl-generator.md */ + comment reqRef /* Requirements: docs/reqstream/api-mark-vhdl/vhdl-generator.yaml */ + } +} diff --git a/docs/sysml2/model/ots.sysml b/docs/sysml2/model/ots.sysml new file mode 100644 index 0000000..7785290 --- /dev/null +++ b/docs/sysml2/model/ots.sysml @@ -0,0 +1,51 @@ +package OtsDependencies { + doc /* Off-the-shelf (OTS) dependencies used by ApiMark. */ + + part def MonoCecil { + doc /* OTS: Mono.Cecil, used for reading compiled .NET assemblies without loading them into the current process. */ + + comment designRef /* Design: docs/design/ots/mono-cecil.md */ + comment verificationRef /* Verification: docs/verification/ots/mono-cecil.md */ + comment reqRef /* Requirements: docs/reqstream/ots/mono-cecil.yaml */ + } + + part def Clang { + doc /* OTS: clang (via `clang -ast-dump=json`), used as a static C++ parser to produce a JSON AST for public headers. */ + + comment designRef /* Design: docs/design/ots/clang.md */ + comment verificationRef /* Verification: docs/verification/ots/clang.md */ + comment reqRef /* Requirements: docs/reqstream/ots/clang.yaml */ + } + + part def TestResults { + doc /* OTS: DemaConsulting.TestResults, used by the SelfTest subsystem to record and serialize self-validation outcomes. */ + + comment designRef /* Design: docs/design/ots/dema-consulting-test-results.md */ + comment verificationRef /* Verification: docs/verification/ots/dema-consulting-test-results.md */ + comment reqRef /* Requirements: docs/reqstream/ots/dema-consulting-test-results.yaml */ + } + + part def Antlr4RuntimeStandard { + doc /* OTS: Antlr4.Runtime.Standard with an ANTLR4 vhdl2008 grammar, used to parse VHDL source files. */ + + comment designRef /* Design: docs/design/ots/antlr4.md */ + comment verificationRef /* Verification: docs/verification/ots/antlr4.md */ + comment reqRef /* Requirements: docs/reqstream/ots/antlr4.yaml */ + } + + part def FileSystemGlobbing { + doc /* OTS: Microsoft.Extensions.FileSystemGlobbing, used for glob-based file discovery in ApiMarkCore. */ + + comment designRef /* Design: docs/design/ots/file-system-globbing.md */ + comment verificationRef /* Verification: docs/verification/ots/file-system-globbing.md */ + comment reqRef /* Requirements: docs/reqstream/ots/file-system-globbing.yaml */ + } + + part def CppAstNet { + doc /* OTS: archived — retained for historical reference; not referenced by any current system. */ + + comment designRef /* Design: docs/design/ots/cpp-ast-net.md */ + comment verificationRef /* Verification: docs/verification/ots/cpp-ast-net.md */ + comment reqRef /* Requirements: docs/reqstream/ots/cpp-ast-net.yaml */ + } +} diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml new file mode 100644 index 0000000..47448a0 --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,68 @@ +// Views rendered into docs/design/generated/ for the Design document. +// Reopens each system's package so each 'expose' statement can reference its target part +// def directly. Per SysML2Tools syntax, 'expose' is only valid inside a named 'view' usage +// (not a 'view def' definition), and it - not 'render' - is what scopes the rendered +// diagram content. ApiMark has six independent system packages (unlike a single-system +// repository), so SoftwareStructureView exposes each system package individually to produce +// one coherent overview diagram. +package ApiMarkCore { + view SoftwareStructureView { + expose ApiMarkCore; + expose ApiMarkDotNet; + expose ApiMarkCpp; + expose ApiMarkVhdl; + expose ApiMarkMsbuild; + expose ApiMarkTool; + render asTreeDiagram; + } + + view ApiMarkCoreView { + expose ApiMarkCoreSystem; + render asTreeDiagram; + } +} + +package ApiMarkDotNet { + view ApiMarkDotNetView { + expose ApiMarkDotNetSystem; + render asTreeDiagram; + } +} + +package ApiMarkCpp { + view ApiMarkCppView { + expose ApiMarkCppSystem; + render asTreeDiagram; + } +} + +package ApiMarkVhdl { + view ApiMarkVhdlView { + expose ApiMarkVhdlSystem; + render asTreeDiagram; + } +} + +package ApiMarkMsbuild { + view ApiMarkMsbuildView { + expose ApiMarkMsbuildSystem; + render asTreeDiagram; + } +} + +package ApiMarkTool { + view ApiMarkToolView { + expose ApiMarkToolSystem; + render asTreeDiagram; + } + + view CliView { + expose CliSubsystem; + render asTreeDiagram; + } + + view SelfTestView { + expose SelfTestSubsystem; + render asTreeDiagram; + } +} From ddaac7fc88f19aa7941816958f30a74c6ffe3885 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:21:01 -0400 Subject: [PATCH 4/7] docs: replace Software Structure ASCII tree with generated diagram Remove the duplicate SoftwareStructureView.svg embed that was placed right after the # Introduction heading, and replace the hand-maintained ASCII Software Structure tree under ## Software Structure with a short explanatory paragraph plus the diagram embed, matching the sysml2-modeling.md standard and DictionaryMark precedent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/design/introduction.md | 66 ++++--------------------------------- 1 file changed, 6 insertions(+), 60 deletions(-) diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 8f9ae75..891cfa9 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -1,7 +1,5 @@ # Introduction -![Software Structure](generated/SoftwareStructureView.svg) - ApiMark generates compact, AI-friendly API reference documentation in Markdown from source code and its associated metadata (XML doc comments, header files, docstrings, etc.). The output is designed for gradual disclosure: an AI can read a lightweight @@ -44,64 +42,12 @@ configuration; the internal design of OTS items is also excluded. ## Software Structure -```text -ApiMarkCore (System) -├── IApiGenerator (Unit) -├── IApiEmitter (Unit) -├── EmitConfig + OutputFormat (Unit) -├── IContext (Unit) -├── IMarkdownWriterFactory (Unit) -├── FileMarkdownWriterFactory (Unit) -├── IMarkdownWriter (Unit) -├── FileMarkdownWriter (Unit) -├── PathHelpers (Unit) -└── GlobFileCollector (Unit) - -ApiMarkDotNet (System) -├── DotNetGenerator (Unit) -├── DotNetAstModel (Unit) -├── DotNetEmitter (Unit) -├── DotNetEmitterGradualDisclosure (Unit) -├── DotNetEmitterSingleFile (Unit) -├── TypeLinkResolver (Unit) -├── XmlDocReader (Unit) -└── TypeNameSimplifier (Unit) - -ApiMarkCpp (System) -├── CppGenerator (Unit) -├── CppAstModel (Unit) -├── ClangAstParser (Unit) -├── CppEmitter (Unit) -├── CppEmitterGradualDisclosure (Unit) -├── CppEmitterSingleFile (Unit) -└── CppTypeLinkResolver (Unit) - -ApiMarkVhdl (System) -├── VhdlGenerator (Unit) -├── VhdlAstModel (Unit) -├── VhdlAstParser (Unit) -├── VhdlEmitter (Unit) -├── VhdlEmitterGradualDisclosure (Unit) -└── VhdlEmitterSingleFile (Unit) - -ApiMarkMsbuild (System) -└── ApiMarkTask (Unit) - -ApiMarkTool (System) -├── Cli (Subsystem) -│ └── Context (Unit) -├── SelfTest (Subsystem) -│ └── Validation (Unit) -└── Program (Unit) - -OTS Dependencies: -├── Mono.Cecil (OTS) -├── DemaConsulting.TestResults (OTS) -├── clang -ast-dump=json (OTS) -├── Antlr4.Runtime.Standard / ANTLR4 vhdl2008 grammar (OTS) -├── Microsoft.Extensions.FileSystemGlobbing (OTS) -└── cpp-ast-net (OTS) [archived] -``` +The software structure is modeled in SysML2 under `docs/sysml2/` and rendered to the +diagram below by SysML2Tools as part of the build pipeline. AI agents should query the +SysML2 model directly (see the `sysml2tools-query` skill) rather than parsing this +diagram or the prose below. + +![Software Structure](generated/SoftwareStructureView.svg) ## Folder Layout From 34cc80446b8f6828f78f5e50e2757dbdadbea7eb Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:01:32 -0400 Subject: [PATCH 5/7] fix: correct SysML2 diagram embed paths and de-enumerate Companion Artifact Structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all 44 docs/design/**/*.md SysML2 diagram embeds to use bare filenames (e.g. SoftwareStructureView.svg) instead of path-prefixed references (generated/..., ../generated/..., ../../generated/...). sysml2tools renders all SVGs flat into docs/design/generated/, and Pandoc's --output design.html lands in that same flat folder without rewriting image paths, so WeasyPrint (which resolves relative image URLs against the HTML file's own location) was failing to find every diagram — silently dropping them from the built PDF. Reproduced and confirmed the failure mode directly with WeasyPrint before/after (broken paths raised 'Failed to load image ... generated/generated/ ...View.svg' errors; fixed paths raise no errors and produce a visibly larger PDF from the now-embedded diagrams). - Replace introduction.md's ~80-line enumeration of every companion artifact file with the terse, pattern-based form the template and sysml2-modeling.md actually specify (parallel path patterns using {system-name}/{subsystem}/{item} placeholders), matching the DictionaryMark precedent. The full enumeration duplicated what the SysML2 model's artifact-ref comments already provide per-item via 'sysml2tools query describe', and would require manual upkeep on every unit addition. Verified: dotnet sysml2tools render, pandoc, and weasyprint all succeed with the fixed paths; pwsh ./lint.ps1 passes clean (0 errors). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/design/api-mark-core.md | 2 +- docs/design/api-mark-core/emit-config.md | 2 +- .../file-markdown-writer-factory.md | 2 +- .../api-mark-core/file-markdown-writer.md | 2 +- .../api-mark-core/glob-file-collector.md | 2 +- docs/design/api-mark-core/i-api-emitter.md | 2 +- docs/design/api-mark-core/i-api-generator.md | 2 +- docs/design/api-mark-core/i-context.md | 2 +- .../i-markdown-writer-factory.md | 2 +- .../design/api-mark-core/i-markdown-writer.md | 2 +- docs/design/api-mark-core/path-helpers.md | 2 +- docs/design/api-mark-cpp.md | 2 +- docs/design/api-mark-cpp/clang-ast-parser.md | 2 +- docs/design/api-mark-cpp/cpp-ast-model.md | 2 +- .../cpp-emitter-gradual-disclosure.md | 2 +- .../api-mark-cpp/cpp-emitter-single-file.md | 2 +- docs/design/api-mark-cpp/cpp-emitter.md | 2 +- docs/design/api-mark-cpp/cpp-generator.md | 2 +- .../api-mark-cpp/cpp-type-link-resolver.md | 2 +- docs/design/api-mark-dot-net.md | 2 +- .../api-mark-dot-net/dot-net-ast-model.md | 2 +- .../dot-net-emitter-gradual-disclosure.md | 2 +- .../dot-net-emitter-single-file.md | 2 +- .../api-mark-dot-net/dot-net-emitter.md | 2 +- .../api-mark-dot-net/dot-net-generator.md | 2 +- .../api-mark-dot-net/type-link-resolver.md | 2 +- .../api-mark-dot-net/type-name-simplifier.md | 2 +- .../design/api-mark-dot-net/xml-doc-reader.md | 2 +- docs/design/api-mark-msbuild.md | 2 +- docs/design/api-mark-msbuild/api-mark-task.md | 2 +- docs/design/api-mark-tool.md | 2 +- docs/design/api-mark-tool/cli.md | 2 +- docs/design/api-mark-tool/cli/context.md | 2 +- docs/design/api-mark-tool/program.md | 2 +- docs/design/api-mark-tool/self-test.md | 2 +- .../api-mark-tool/self-test/validation.md | 2 +- docs/design/api-mark-vhdl.md | 2 +- docs/design/api-mark-vhdl/vhdl-ast-model.md | 2 +- docs/design/api-mark-vhdl/vhdl-ast-parser.md | 2 +- .../vhdl-emitter-gradual-disclosure.md | 2 +- .../api-mark-vhdl/vhdl-emitter-single-file.md | 2 +- docs/design/api-mark-vhdl/vhdl-emitter.md | 2 +- docs/design/api-mark-vhdl/vhdl-generator.md | 2 +- docs/design/introduction.md | 134 ++---------------- 44 files changed, 58 insertions(+), 162 deletions(-) diff --git a/docs/design/api-mark-core.md b/docs/design/api-mark-core.md index a210d53..64e11c4 100644 --- a/docs/design/api-mark-core.md +++ b/docs/design/api-mark-core.md @@ -1,6 +1,6 @@ # ApiMarkCore -![ApiMarkCore Structure](generated/ApiMarkCoreView.svg) +![ApiMarkCore Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/emit-config.md b/docs/design/api-mark-core/emit-config.md index 2fa751c..f6ffe9e 100644 --- a/docs/design/api-mark-core/emit-config.md +++ b/docs/design/api-mark-core/emit-config.md @@ -1,6 +1,6 @@ ## EmitConfig and OutputFormat -![EmitConfig Structure](../generated/ApiMarkCoreView.svg) +![EmitConfig Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/file-markdown-writer-factory.md b/docs/design/api-mark-core/file-markdown-writer-factory.md index a93e7dd..1c04a24 100644 --- a/docs/design/api-mark-core/file-markdown-writer-factory.md +++ b/docs/design/api-mark-core/file-markdown-writer-factory.md @@ -1,6 +1,6 @@ ## FileMarkdownWriterFactory -![FileMarkdownWriterFactory Structure](../generated/ApiMarkCoreView.svg) +![FileMarkdownWriterFactory Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/file-markdown-writer.md b/docs/design/api-mark-core/file-markdown-writer.md index 1a9bdd1..8ed573c 100644 --- a/docs/design/api-mark-core/file-markdown-writer.md +++ b/docs/design/api-mark-core/file-markdown-writer.md @@ -1,6 +1,6 @@ ## FileMarkdownWriter -![FileMarkdownWriter Structure](../generated/ApiMarkCoreView.svg) +![FileMarkdownWriter Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/glob-file-collector.md b/docs/design/api-mark-core/glob-file-collector.md index dd7989f..4c5b8c7 100644 --- a/docs/design/api-mark-core/glob-file-collector.md +++ b/docs/design/api-mark-core/glob-file-collector.md @@ -1,6 +1,6 @@ ## GlobFileCollector -![GlobFileCollector Structure](../generated/ApiMarkCoreView.svg) +![GlobFileCollector Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/i-api-emitter.md b/docs/design/api-mark-core/i-api-emitter.md index 8ec98be..2c29289 100644 --- a/docs/design/api-mark-core/i-api-emitter.md +++ b/docs/design/api-mark-core/i-api-emitter.md @@ -1,6 +1,6 @@ ## IApiEmitter -![IApiEmitter Structure](../generated/ApiMarkCoreView.svg) +![IApiEmitter Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/i-api-generator.md b/docs/design/api-mark-core/i-api-generator.md index 6e4bebc..e158d1d 100644 --- a/docs/design/api-mark-core/i-api-generator.md +++ b/docs/design/api-mark-core/i-api-generator.md @@ -1,6 +1,6 @@ ## IApiGenerator -![IApiGenerator Structure](../generated/ApiMarkCoreView.svg) +![IApiGenerator Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/i-context.md b/docs/design/api-mark-core/i-context.md index 5abff3b..cf966a4 100644 --- a/docs/design/api-mark-core/i-context.md +++ b/docs/design/api-mark-core/i-context.md @@ -1,6 +1,6 @@ ## IContext -![IContext Structure](../generated/ApiMarkCoreView.svg) +![IContext Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/i-markdown-writer-factory.md b/docs/design/api-mark-core/i-markdown-writer-factory.md index 162222d..7c53ed5 100644 --- a/docs/design/api-mark-core/i-markdown-writer-factory.md +++ b/docs/design/api-mark-core/i-markdown-writer-factory.md @@ -1,6 +1,6 @@ ## IMarkdownWriterFactory -![IMarkdownWriterFactory Structure](../generated/ApiMarkCoreView.svg) +![IMarkdownWriterFactory Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/i-markdown-writer.md b/docs/design/api-mark-core/i-markdown-writer.md index a11d9da..def68e6 100644 --- a/docs/design/api-mark-core/i-markdown-writer.md +++ b/docs/design/api-mark-core/i-markdown-writer.md @@ -1,6 +1,6 @@ ## IMarkdownWriter -![IMarkdownWriter Structure](../generated/ApiMarkCoreView.svg) +![IMarkdownWriter Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-core/path-helpers.md b/docs/design/api-mark-core/path-helpers.md index 86a882f..e88d2a2 100644 --- a/docs/design/api-mark-core/path-helpers.md +++ b/docs/design/api-mark-core/path-helpers.md @@ -1,6 +1,6 @@ ## PathHelpers -![PathHelpers Structure](../generated/ApiMarkCoreView.svg) +![PathHelpers Structure](ApiMarkCoreView.svg) diff --git a/docs/design/api-mark-cpp.md b/docs/design/api-mark-cpp.md index 1680dc7..57e37c7 100644 --- a/docs/design/api-mark-cpp.md +++ b/docs/design/api-mark-cpp.md @@ -1,6 +1,6 @@ # ApiMarkCpp -![ApiMarkCpp Structure](generated/ApiMarkCppView.svg) +![ApiMarkCpp Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/clang-ast-parser.md b/docs/design/api-mark-cpp/clang-ast-parser.md index a293415..9cdca97 100644 --- a/docs/design/api-mark-cpp/clang-ast-parser.md +++ b/docs/design/api-mark-cpp/clang-ast-parser.md @@ -1,6 +1,6 @@ ## ClangAstParser -![ClangAstParser Structure](../generated/ApiMarkCppView.svg) +![ClangAstParser Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-ast-model.md b/docs/design/api-mark-cpp/cpp-ast-model.md index 07a583f..dcbcfe6 100644 --- a/docs/design/api-mark-cpp/cpp-ast-model.md +++ b/docs/design/api-mark-cpp/cpp-ast-model.md @@ -1,6 +1,6 @@ ## CppAstModel -![CppAstModel Structure](../generated/ApiMarkCppView.svg) +![CppAstModel Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md b/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md index f673470..44079b0 100644 --- a/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md @@ -1,6 +1,6 @@ ## CppEmitterGradualDisclosure -![CppEmitterGradualDisclosure Structure](../generated/ApiMarkCppView.svg) +![CppEmitterGradualDisclosure Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-emitter-single-file.md b/docs/design/api-mark-cpp/cpp-emitter-single-file.md index 63e59b0..ff3bd28 100644 --- a/docs/design/api-mark-cpp/cpp-emitter-single-file.md +++ b/docs/design/api-mark-cpp/cpp-emitter-single-file.md @@ -1,6 +1,6 @@ ## CppEmitterSingleFile -![CppEmitterSingleFile Structure](../generated/ApiMarkCppView.svg) +![CppEmitterSingleFile Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-emitter.md b/docs/design/api-mark-cpp/cpp-emitter.md index e233c9e..6bfd4b3 100644 --- a/docs/design/api-mark-cpp/cpp-emitter.md +++ b/docs/design/api-mark-cpp/cpp-emitter.md @@ -1,6 +1,6 @@ ## CppEmitter -![CppEmitter Structure](../generated/ApiMarkCppView.svg) +![CppEmitter Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-generator.md b/docs/design/api-mark-cpp/cpp-generator.md index 74d6135..067f683 100644 --- a/docs/design/api-mark-cpp/cpp-generator.md +++ b/docs/design/api-mark-cpp/cpp-generator.md @@ -1,6 +1,6 @@ ## CppGenerator -![CppGenerator Structure](../generated/ApiMarkCppView.svg) +![CppGenerator Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-cpp/cpp-type-link-resolver.md b/docs/design/api-mark-cpp/cpp-type-link-resolver.md index 45b1717..48390de 100644 --- a/docs/design/api-mark-cpp/cpp-type-link-resolver.md +++ b/docs/design/api-mark-cpp/cpp-type-link-resolver.md @@ -1,6 +1,6 @@ ## CppTypeLinkResolver -![CppTypeLinkResolver Structure](../generated/ApiMarkCppView.svg) +![CppTypeLinkResolver Structure](ApiMarkCppView.svg) diff --git a/docs/design/api-mark-dot-net.md b/docs/design/api-mark-dot-net.md index 7c0305c..6058e33 100644 --- a/docs/design/api-mark-dot-net.md +++ b/docs/design/api-mark-dot-net.md @@ -1,6 +1,6 @@ # ApiMarkDotNet -![ApiMarkDotNet Structure](generated/ApiMarkDotNetView.svg) +![ApiMarkDotNet Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/dot-net-ast-model.md b/docs/design/api-mark-dot-net/dot-net-ast-model.md index b7e61ed..80ad965 100644 --- a/docs/design/api-mark-dot-net/dot-net-ast-model.md +++ b/docs/design/api-mark-dot-net/dot-net-ast-model.md @@ -1,6 +1,6 @@ ## DotNetAstModel -![DotNetAstModel Structure](../generated/ApiMarkDotNetView.svg) +![DotNetAstModel Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md b/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md index 6c0e2a3..3527869 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md @@ -1,6 +1,6 @@ ## DotNetEmitterGradualDisclosure -![DotNetEmitterGradualDisclosure Structure](../generated/ApiMarkDotNetView.svg) +![DotNetEmitterGradualDisclosure Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md b/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md index 587a527..5a47224 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter-single-file.md @@ -1,6 +1,6 @@ ## DotNetEmitterSingleFile -![DotNetEmitterSingleFile Structure](../generated/ApiMarkDotNetView.svg) +![DotNetEmitterSingleFile Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/dot-net-emitter.md b/docs/design/api-mark-dot-net/dot-net-emitter.md index f8c2c2f..156dfaa 100644 --- a/docs/design/api-mark-dot-net/dot-net-emitter.md +++ b/docs/design/api-mark-dot-net/dot-net-emitter.md @@ -1,6 +1,6 @@ ## DotNetEmitter -![DotNetEmitter Structure](../generated/ApiMarkDotNetView.svg) +![DotNetEmitter Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/dot-net-generator.md b/docs/design/api-mark-dot-net/dot-net-generator.md index 8b00ae4..f3f2ad3 100644 --- a/docs/design/api-mark-dot-net/dot-net-generator.md +++ b/docs/design/api-mark-dot-net/dot-net-generator.md @@ -1,6 +1,6 @@ ## DotNetGenerator -![DotNetGenerator Structure](../generated/ApiMarkDotNetView.svg) +![DotNetGenerator Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/type-link-resolver.md b/docs/design/api-mark-dot-net/type-link-resolver.md index 26605af..45eaae1 100644 --- a/docs/design/api-mark-dot-net/type-link-resolver.md +++ b/docs/design/api-mark-dot-net/type-link-resolver.md @@ -1,6 +1,6 @@ ## TypeLinkResolver -![TypeLinkResolver Structure](../generated/ApiMarkDotNetView.svg) +![TypeLinkResolver Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/type-name-simplifier.md b/docs/design/api-mark-dot-net/type-name-simplifier.md index c424c1b..813ab6f 100644 --- a/docs/design/api-mark-dot-net/type-name-simplifier.md +++ b/docs/design/api-mark-dot-net/type-name-simplifier.md @@ -1,6 +1,6 @@ ## TypeNameSimplifier -![TypeNameSimplifier Structure](../generated/ApiMarkDotNetView.svg) +![TypeNameSimplifier Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-dot-net/xml-doc-reader.md b/docs/design/api-mark-dot-net/xml-doc-reader.md index 43517a5..d6ffa54 100644 --- a/docs/design/api-mark-dot-net/xml-doc-reader.md +++ b/docs/design/api-mark-dot-net/xml-doc-reader.md @@ -1,6 +1,6 @@ ## XmlDocReader -![XmlDocReader Structure](../generated/ApiMarkDotNetView.svg) +![XmlDocReader Structure](ApiMarkDotNetView.svg) diff --git a/docs/design/api-mark-msbuild.md b/docs/design/api-mark-msbuild.md index 562a955..45f590c 100644 --- a/docs/design/api-mark-msbuild.md +++ b/docs/design/api-mark-msbuild.md @@ -1,6 +1,6 @@ # ApiMarkMsbuild -![ApiMarkMsbuild Structure](generated/ApiMarkMsbuildView.svg) +![ApiMarkMsbuild Structure](ApiMarkMsbuildView.svg) diff --git a/docs/design/api-mark-msbuild/api-mark-task.md b/docs/design/api-mark-msbuild/api-mark-task.md index 55c4052..5daf2dd 100644 --- a/docs/design/api-mark-msbuild/api-mark-task.md +++ b/docs/design/api-mark-msbuild/api-mark-task.md @@ -1,6 +1,6 @@ ## ApiMarkTask -![ApiMarkTask Structure](../generated/ApiMarkMsbuildView.svg) +![ApiMarkTask Structure](ApiMarkMsbuildView.svg) diff --git a/docs/design/api-mark-tool.md b/docs/design/api-mark-tool.md index 5c5321d..66b37ee 100644 --- a/docs/design/api-mark-tool.md +++ b/docs/design/api-mark-tool.md @@ -1,6 +1,6 @@ # ApiMarkTool -![ApiMarkTool Structure](generated/ApiMarkToolView.svg) +![ApiMarkTool Structure](ApiMarkToolView.svg) diff --git a/docs/design/api-mark-tool/cli.md b/docs/design/api-mark-tool/cli.md index 260e23a..5a89ad3 100644 --- a/docs/design/api-mark-tool/cli.md +++ b/docs/design/api-mark-tool/cli.md @@ -1,6 +1,6 @@ ## Cli -![Cli Structure](../generated/CliView.svg) +![Cli Structure](CliView.svg) diff --git a/docs/design/api-mark-tool/cli/context.md b/docs/design/api-mark-tool/cli/context.md index 0111e46..37dcb32 100644 --- a/docs/design/api-mark-tool/cli/context.md +++ b/docs/design/api-mark-tool/cli/context.md @@ -1,6 +1,6 @@ ### Context -![Context Structure](../../generated/CliView.svg) +![Context Structure](CliView.svg) diff --git a/docs/design/api-mark-tool/program.md b/docs/design/api-mark-tool/program.md index 6d5102e..77eb286 100644 --- a/docs/design/api-mark-tool/program.md +++ b/docs/design/api-mark-tool/program.md @@ -1,6 +1,6 @@ ## Program -![Program Structure](../generated/ApiMarkToolView.svg) +![Program Structure](ApiMarkToolView.svg) diff --git a/docs/design/api-mark-tool/self-test.md b/docs/design/api-mark-tool/self-test.md index 7027891..c187098 100644 --- a/docs/design/api-mark-tool/self-test.md +++ b/docs/design/api-mark-tool/self-test.md @@ -1,6 +1,6 @@ ## SelfTest -![SelfTest Structure](../generated/SelfTestView.svg) +![SelfTest Structure](SelfTestView.svg) diff --git a/docs/design/api-mark-tool/self-test/validation.md b/docs/design/api-mark-tool/self-test/validation.md index d698259..b415371 100644 --- a/docs/design/api-mark-tool/self-test/validation.md +++ b/docs/design/api-mark-tool/self-test/validation.md @@ -1,6 +1,6 @@ ### Validation -![Validation Structure](../../generated/SelfTestView.svg) +![Validation Structure](SelfTestView.svg) diff --git a/docs/design/api-mark-vhdl.md b/docs/design/api-mark-vhdl.md index 5d13d72..7bf56c0 100644 --- a/docs/design/api-mark-vhdl.md +++ b/docs/design/api-mark-vhdl.md @@ -1,6 +1,6 @@ # ApiMarkVhdl -![ApiMarkVhdl Structure](generated/ApiMarkVhdlView.svg) +![ApiMarkVhdl Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-ast-model.md b/docs/design/api-mark-vhdl/vhdl-ast-model.md index c87bd93..59fceb8 100644 --- a/docs/design/api-mark-vhdl/vhdl-ast-model.md +++ b/docs/design/api-mark-vhdl/vhdl-ast-model.md @@ -1,6 +1,6 @@ ## VhdlAstModel -![VhdlAstModel Structure](../generated/ApiMarkVhdlView.svg) +![VhdlAstModel Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-ast-parser.md b/docs/design/api-mark-vhdl/vhdl-ast-parser.md index 13db2cb..df90362 100644 --- a/docs/design/api-mark-vhdl/vhdl-ast-parser.md +++ b/docs/design/api-mark-vhdl/vhdl-ast-parser.md @@ -1,6 +1,6 @@ ## VhdlAstParser -![VhdlAstParser Structure](../generated/ApiMarkVhdlView.svg) +![VhdlAstParser Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md b/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md index 9d951da..d567af7 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md @@ -1,6 +1,6 @@ ## VhdlEmitterGradualDisclosure -![VhdlEmitterGradualDisclosure Structure](../generated/ApiMarkVhdlView.svg) +![VhdlEmitterGradualDisclosure Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md b/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md index 01727da..25e96c0 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter-single-file.md @@ -1,6 +1,6 @@ ## VhdlEmitterSingleFile -![VhdlEmitterSingleFile Structure](../generated/ApiMarkVhdlView.svg) +![VhdlEmitterSingleFile Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-emitter.md b/docs/design/api-mark-vhdl/vhdl-emitter.md index 9674b9c..892f072 100644 --- a/docs/design/api-mark-vhdl/vhdl-emitter.md +++ b/docs/design/api-mark-vhdl/vhdl-emitter.md @@ -1,6 +1,6 @@ ## VhdlEmitter -![VhdlEmitter Structure](../generated/ApiMarkVhdlView.svg) +![VhdlEmitter Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/api-mark-vhdl/vhdl-generator.md b/docs/design/api-mark-vhdl/vhdl-generator.md index ca75bb8..522fea6 100644 --- a/docs/design/api-mark-vhdl/vhdl-generator.md +++ b/docs/design/api-mark-vhdl/vhdl-generator.md @@ -1,6 +1,6 @@ ## VhdlGenerator -![VhdlGenerator Structure](../generated/ApiMarkVhdlView.svg) +![VhdlGenerator Structure](ApiMarkVhdlView.svg) diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 891cfa9..1d39e8b 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -47,7 +47,7 @@ diagram below by SysML2Tools as part of the build pipeline. AI agents should que SysML2 model directly (see the `sysml2tools-query` skill) rather than parsing this diagram or the prose below. -![Software Structure](generated/SoftwareStructureView.svg) +![Software Structure](SoftwareStructureView.svg) ## Folder Layout @@ -69,127 +69,23 @@ src/ Each local software item has corresponding artifacts in parallel directory trees: -- Requirements: `docs/reqstream/api-mark-core.yaml`, `docs/reqstream/api-mark-core/{item}.yaml`, `docs/reqstream/api-mark-dot-net.yaml`, - `docs/reqstream/api-mark-dot-net/dot-net-generator.yaml`, - `docs/reqstream/api-mark-dot-net/type-name-simplifier.yaml`, - `docs/reqstream/api-mark-dot-net/dot-net-ast-model.yaml`, - `docs/reqstream/api-mark-dot-net/dot-net-emitter.yaml`, - `docs/reqstream/api-mark-dot-net/dot-net-emitter-gradual-disclosure.yaml`, - `docs/reqstream/api-mark-dot-net/dot-net-emitter-single-file.yaml`, - `docs/reqstream/api-mark-dot-net/type-link-resolver.yaml`, - `docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml`, - `docs/reqstream/api-mark-cpp.yaml`, - `docs/reqstream/api-mark-cpp/cpp-generator.yaml`, - `docs/reqstream/api-mark-cpp/cpp-ast-model.yaml`, - `docs/reqstream/api-mark-cpp/clang-ast-parser.yaml`, - `docs/reqstream/api-mark-cpp/cpp-emitter.yaml`, - `docs/reqstream/api-mark-cpp/cpp-emitter-gradual-disclosure.yaml`, - `docs/reqstream/api-mark-cpp/cpp-emitter-single-file.yaml`, - `docs/reqstream/api-mark-cpp/cpp-type-link-resolver.yaml`, - `docs/reqstream/api-mark-vhdl.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-generator.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-ast-model.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-ast-parser.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-emitter.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-emitter-gradual-disclosure.yaml`, - `docs/reqstream/api-mark-vhdl/vhdl-emitter-single-file.yaml`, - `docs/reqstream/api-mark-msbuild.yaml`, `docs/reqstream/api-mark-msbuild/{item}.yaml`, - `docs/reqstream/api-mark-tool.yaml`, `docs/reqstream/api-mark-tool/{item}.yaml` -- Design: `docs/design/api-mark-core.md`, `docs/design/api-mark-core/{item}.md`, - `docs/design/api-mark-dot-net.md`, - `docs/design/api-mark-dot-net/dot-net-generator.md`, - `docs/design/api-mark-dot-net/type-name-simplifier.md`, - `docs/design/api-mark-dot-net/dot-net-ast-model.md`, - `docs/design/api-mark-dot-net/dot-net-emitter.md`, - `docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md`, - `docs/design/api-mark-dot-net/dot-net-emitter-single-file.md`, - `docs/design/api-mark-dot-net/type-link-resolver.md`, - `docs/design/api-mark-dot-net/xml-doc-reader.md`, - `docs/design/api-mark-cpp.md`, - `docs/design/api-mark-cpp/cpp-generator.md`, - `docs/design/api-mark-cpp/cpp-ast-model.md`, - `docs/design/api-mark-cpp/clang-ast-parser.md`, - `docs/design/api-mark-cpp/cpp-emitter.md`, - `docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md`, - `docs/design/api-mark-cpp/cpp-emitter-single-file.md`, - `docs/design/api-mark-cpp/cpp-type-link-resolver.md`, - `docs/design/api-mark-vhdl.md`, - `docs/design/api-mark-vhdl/vhdl-generator.md`, - `docs/design/api-mark-vhdl/vhdl-ast-model.md`, - `docs/design/api-mark-vhdl/vhdl-ast-parser.md`, - `docs/design/api-mark-vhdl/vhdl-emitter.md`, - `docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md`, - `docs/design/api-mark-vhdl/vhdl-emitter-single-file.md`, - `docs/design/api-mark-msbuild.md`, `docs/design/api-mark-msbuild/{item}.md`, - `docs/design/api-mark-tool.md`, `docs/design/api-mark-tool/{item}.md` -- Verification: `docs/verification/api-mark-core.md`, `docs/verification/api-mark-core/{item}.md`, - `docs/verification/api-mark-dot-net.md`, - `docs/verification/api-mark-dot-net/dot-net-generator.md`, - `docs/verification/api-mark-dot-net/type-name-simplifier.md`, - `docs/verification/api-mark-dot-net/dot-net-ast-model.md`, - `docs/verification/api-mark-dot-net/dot-net-emitter.md`, - `docs/verification/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md`, - `docs/verification/api-mark-dot-net/dot-net-emitter-single-file.md`, - `docs/verification/api-mark-dot-net/type-link-resolver.md`, - `docs/verification/api-mark-dot-net/xml-doc-reader.md`, - `docs/verification/api-mark-cpp.md`, - `docs/verification/api-mark-cpp/cpp-generator.md`, - `docs/verification/api-mark-cpp/cpp-ast-model.md`, - `docs/verification/api-mark-cpp/clang-ast-parser.md`, - `docs/verification/api-mark-cpp/cpp-emitter.md`, - `docs/verification/api-mark-cpp/cpp-emitter-gradual-disclosure.md`, - `docs/verification/api-mark-cpp/cpp-emitter-single-file.md`, - `docs/verification/api-mark-cpp/cpp-type-link-resolver.md`, - `docs/verification/api-mark-vhdl.md`, - `docs/verification/api-mark-vhdl/vhdl-generator.md`, - `docs/verification/api-mark-vhdl/vhdl-ast-model.md`, - `docs/verification/api-mark-vhdl/vhdl-ast-parser.md`, - `docs/verification/api-mark-vhdl/vhdl-emitter.md`, - `docs/verification/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md`, - `docs/verification/api-mark-vhdl/vhdl-emitter-single-file.md`, - `docs/verification/api-mark-msbuild.md`, `docs/verification/api-mark-msbuild/{item}.md`, - `docs/verification/api-mark-tool.md`, `docs/verification/api-mark-tool/{item}.md` -- Source: `src/ApiMark.Core/`, `src/ApiMark.DotNet/`, `src/ApiMark.Cpp/`, `src/ApiMark.Vhdl/`, - `src/ApiMark.MSBuild/`, `src/ApiMark.Tool/` -- Tests: `test/ApiMark.Core.TestHelpers/`, `test/ApiMark.Core.Tests/`, `test/ApiMark.DotNet.Tests/`, - `test/ApiMark.Cpp.Tests/`, `test/ApiMark.Vhdl.Tests/`, - `test/ApiMark.MSBuild.Tests/`, `test/ApiMark.MSBuild.PackageTests/`, `test/ApiMark.Tool.Tests/` -- Fixtures: `test/ApiMark.DotNet.Fixtures/`, `test/ApiMark.Cpp.Fixtures/` +- Requirements: `docs/reqstream/{system-name}.yaml`, + `docs/reqstream/{system-name}/{subsystem}/{item}.yaml` +- Design: `docs/design/{system-name}.md`, + `docs/design/{system-name}/{subsystem}/{item}.md` +- Verification: `docs/verification/{system-name}.md`, + `docs/verification/{system-name}/{subsystem}/{item}.md` +- Source: `src/ApiMark.{SystemName}/{Subsystem}/{Item}.cs` +- Tests: `test/ApiMark.{SystemName}.Tests/{Subsystem}/{Item}Tests.cs` -OTS items have integration/usage design documentation parallel to system folders: - -- Design: `docs/design/ots/mono-cecil.md` -- Verification: `docs/verification/ots/mono-cecil.md` - -And for clang: - -- Requirements: `docs/reqstream/ots/clang.yaml` -- Design: `docs/design/ots/clang.md` -- Verification: `docs/verification/ots/clang.md` - -And for DemaConsulting.TestResults: - -- Requirements: `docs/reqstream/ots/dema-consulting-test-results.yaml` -- Design: `docs/design/ots/dema-consulting-test-results.md` -- Verification: `docs/verification/ots/dema-consulting-test-results.md` +Fixtures used by generator tests live in `test/ApiMark.DotNet.Fixtures/` and +`test/ApiMark.Cpp.Fixtures/`. -And for ANTLR4: - -- Requirements: `docs/reqstream/ots/antlr4.yaml` -- Design: `docs/design/ots/antlr4.md` -- Verification: `docs/verification/ots/antlr4.md` - -And for Microsoft.Extensions.FileSystemGlobbing: - -- Requirements: `docs/reqstream/ots/file-system-globbing.yaml` -- Design: `docs/design/ots/file-system-globbing.md` -- Verification: `docs/verification/ots/file-system-globbing.md` - -And for cpp-ast-net (archived): +OTS items have integration/usage design documentation parallel to system folders: -- Requirements: `docs/reqstream/ots/cpp-ast-net.yaml` -- Design: `docs/design/ots/cpp-ast-net.md` -- Verification: `docs/verification/ots/cpp-ast-net.md` +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Design: `docs/design/ots/{ots-name}.md` +- Verification: `docs/verification/ots/{ots-name}.md` Review-sets: defined in `.reviewmark.yaml` From 575f5880d8180f8c553cbc6ab587f8ee330df913 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:40:30 -0400 Subject: [PATCH 6/7] chore: remove render asTreeDiagram from design-views.sysml views MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The upstream Agents template is being updated to drop the explicit 'render asTreeDiagram;' statement from every view usage. Verified locally that sysml2tools lint/render/pandoc/weasyprint/fileassert all still succeed without it (render falls back to a different default diagram style — a flat UML-style package/part-def compartment listing rather than the nested containment tree), matching the upcoming template change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/sysml2/views/design-views.sysml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml index 47448a0..f6aa3ae 100644 --- a/docs/sysml2/views/design-views.sysml +++ b/docs/sysml2/views/design-views.sysml @@ -13,56 +13,47 @@ package ApiMarkCore { expose ApiMarkVhdl; expose ApiMarkMsbuild; expose ApiMarkTool; - render asTreeDiagram; } view ApiMarkCoreView { expose ApiMarkCoreSystem; - render asTreeDiagram; } } package ApiMarkDotNet { view ApiMarkDotNetView { expose ApiMarkDotNetSystem; - render asTreeDiagram; } } package ApiMarkCpp { view ApiMarkCppView { expose ApiMarkCppSystem; - render asTreeDiagram; } } package ApiMarkVhdl { view ApiMarkVhdlView { expose ApiMarkVhdlSystem; - render asTreeDiagram; } } package ApiMarkMsbuild { view ApiMarkMsbuildView { expose ApiMarkMsbuildSystem; - render asTreeDiagram; } } package ApiMarkTool { view ApiMarkToolView { expose ApiMarkToolSystem; - render asTreeDiagram; } view CliView { expose CliSubsystem; - render asTreeDiagram; } view SelfTestView { expose SelfTestSubsystem; - render asTreeDiagram; } } From 59d2352b344cae34a8f0875d85c638a5b8b6a55b Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:50:45 -0400 Subject: [PATCH 7/7] Update sysml standard for render option. --- .github/standards/sysml2-modeling.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md index 60f7b96..c5558e1 100644 --- a/.github/standards/sysml2-modeling.md +++ b/.github/standards/sysml2-modeling.md @@ -127,17 +127,14 @@ Views control what gets rendered into diagrams for the design document. Use name package {SystemName} { view SoftwareStructureView { expose {SystemName}; // whole package: system + subsystems + units - render asTreeDiagram; } view {SystemName}View { expose {SystemName}System; // system def only, not expanded into subsystems - render asTreeDiagram; } view {SubsystemName}View { expose {SubsystemName}; // one subsystem def only - render asTreeDiagram; } } ``` @@ -145,7 +142,7 @@ package {SystemName} { **Critical distinction** (do not confuse these — this cost significant trial-and-error to discover): `expose ;` is what scopes a rendered diagram's content (the union of the named element's containment subtree). `render ;` selects a rendering *style* (e.g. -`asTreeDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`asInterconnectionDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named `view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }` **definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`).