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/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..c5558e1 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,232 @@ +--- +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 + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + } +} +``` + +**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. +`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;`). + +**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/.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/.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/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) diff --git a/docs/design/api-mark-core.md b/docs/design/api-mark-core.md index 87a9fdc..64e11c4 100644 --- a/docs/design/api-mark-core.md +++ b/docs/design/api-mark-core.md @@ -1,5 +1,7 @@ # ApiMarkCore +![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 d8457be..f6ffe9e 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](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..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,5 +1,7 @@ ## FileMarkdownWriterFactory +![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 907d04a..8ed573c 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](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..4c5b8c7 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](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..2c29289 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](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..e158d1d 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](ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/i-context.md b/docs/design/api-mark-core/i-context.md index 2c0ae9d..cf966a4 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](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..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,5 +1,7 @@ ## IMarkdownWriterFactory +![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 5e08fc8..def68e6 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](ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-core/path-helpers.md b/docs/design/api-mark-core/path-helpers.md index 22c4152..e88d2a2 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](ApiMarkCoreView.svg) + diff --git a/docs/design/api-mark-cpp.md b/docs/design/api-mark-cpp.md index 9855789..57e37c7 100644 --- a/docs/design/api-mark-cpp.md +++ b/docs/design/api-mark-cpp.md @@ -1,5 +1,7 @@ # ApiMarkCpp +![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 caa030e..9cdca97 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](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..dcbcfe6 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](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..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,5 +1,7 @@ ## CppEmitterGradualDisclosure +![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 e42fe2f..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,5 +1,7 @@ ## CppEmitterSingleFile +![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 99c05eb..6bfd4b3 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](ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-cpp/cpp-generator.md b/docs/design/api-mark-cpp/cpp-generator.md index 8f63a90..067f683 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](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..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,5 +1,7 @@ ## CppTypeLinkResolver +![CppTypeLinkResolver Structure](ApiMarkCppView.svg) + diff --git a/docs/design/api-mark-dot-net.md b/docs/design/api-mark-dot-net.md index 79b0770..6058e33 100644 --- a/docs/design/api-mark-dot-net.md +++ b/docs/design/api-mark-dot-net.md @@ -1,5 +1,7 @@ # ApiMarkDotNet +![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 726d5a1..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,5 +1,7 @@ ## DotNetAstModel +![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 7b8f1e5..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,5 +1,7 @@ ## DotNetEmitterGradualDisclosure +![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 0a6f589..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,5 +1,7 @@ ## DotNetEmitterSingleFile +![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 62049f8..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,5 +1,7 @@ ## DotNetEmitter +![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 1dfd05e..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,5 +1,7 @@ ## DotNetGenerator +![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 b3e1deb..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,5 +1,7 @@ ## TypeLinkResolver +![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 92d2af0..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,5 +1,7 @@ ## TypeNameSimplifier +![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 98f5a8f..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,5 +1,7 @@ ## XmlDocReader +![XmlDocReader Structure](ApiMarkDotNetView.svg) + diff --git a/docs/design/api-mark-msbuild.md b/docs/design/api-mark-msbuild.md index ca0d84d..45f590c 100644 --- a/docs/design/api-mark-msbuild.md +++ b/docs/design/api-mark-msbuild.md @@ -1,5 +1,7 @@ # ApiMarkMsbuild +![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 5dcfe54..5daf2dd 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](ApiMarkMsbuildView.svg) + diff --git a/docs/design/api-mark-tool.md b/docs/design/api-mark-tool.md index 28e26c8..66b37ee 100644 --- a/docs/design/api-mark-tool.md +++ b/docs/design/api-mark-tool.md @@ -1,5 +1,7 @@ # ApiMarkTool +![ApiMarkTool Structure](ApiMarkToolView.svg) + diff --git a/docs/design/api-mark-tool/cli.md b/docs/design/api-mark-tool/cli.md index 22121ea..5a89ad3 100644 --- a/docs/design/api-mark-tool/cli.md +++ b/docs/design/api-mark-tool/cli.md @@ -1,5 +1,7 @@ ## Cli +![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 7511e91..37dcb32 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](CliView.svg) + diff --git a/docs/design/api-mark-tool/program.md b/docs/design/api-mark-tool/program.md index 04a78e6..77eb286 100644 --- a/docs/design/api-mark-tool/program.md +++ b/docs/design/api-mark-tool/program.md @@ -1,5 +1,7 @@ ## Program +![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 8f10fc6..c187098 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](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..b415371 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](SelfTestView.svg) + diff --git a/docs/design/api-mark-vhdl.md b/docs/design/api-mark-vhdl.md index 0840cdb..7bf56c0 100644 --- a/docs/design/api-mark-vhdl.md +++ b/docs/design/api-mark-vhdl.md @@ -1,5 +1,7 @@ # ApiMarkVhdl +![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 a3e285b..59fceb8 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](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..df90362 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](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..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,5 +1,7 @@ ## VhdlEmitterGradualDisclosure +![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 31e06ae..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,5 +1,7 @@ ## VhdlEmitterSingleFile +![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 0bf6532..892f072 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](ApiMarkVhdlView.svg) + diff --git a/docs/design/api-mark-vhdl/vhdl-generator.md b/docs/design/api-mark-vhdl/vhdl-generator.md index 46a96a7..522fea6 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](ApiMarkVhdlView.svg) + diff --git a/docs/design/introduction.md b/docs/design/introduction.md index cbbba69..1d39e8b 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -42,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](SoftwareStructureView.svg) ## Folder Layout @@ -121,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/` - -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/{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` -- Requirements: `docs/reqstream/ots/clang.yaml` -- Design: `docs/design/ots/clang.md` -- Verification: `docs/verification/ots/clang.md` +Fixtures used by generator tests live in `test/ApiMark.DotNet.Fixtures/` and +`test/ApiMark.Cpp.Fixtures/`. -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` - -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` 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..f6aa3ae --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,59 @@ +// 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; + } + + view ApiMarkCoreView { + expose ApiMarkCoreSystem; + } +} + +package ApiMarkDotNet { + view ApiMarkDotNetView { + expose ApiMarkDotNetSystem; + } +} + +package ApiMarkCpp { + view ApiMarkCppView { + expose ApiMarkCppSystem; + } +} + +package ApiMarkVhdl { + view ApiMarkVhdlView { + expose ApiMarkVhdlSystem; + } +} + +package ApiMarkMsbuild { + view ApiMarkMsbuildView { + expose ApiMarkMsbuildSystem; + } +} + +package ApiMarkTool { + view ApiMarkToolView { + expose ApiMarkToolSystem; + } + + view CliView { + expose CliSubsystem; + } + + view SelfTestView { + expose SelfTestSubsystem; + } +} 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.