From dd887e60edf0015e08506c7183a8a18815377e5a Mon Sep 17 00:00:00 2001 From: TheSevenPens <98374109+TheSevenPens@users.noreply.github.com> Date: Sat, 9 May 2026 16:33:13 -0700 Subject: [PATCH] docs: cleanup pass after the VisioScripting public-API thread (#156, #182, #184, #131) Five files updated to bring the in-repo docs in sync with the new hybrid public-API contract that landed end-to-end in this thread: - VisioScripting/README.md: split "Key types" into public-stable vs internal plumbing. CommandTarget / CommandTargetFlags are now flagged as internal post-Phase-C; Loaders/ entry notes reach via Client.Model.Load*FromXml; Helpers/ entry notes the [InternalsVisibleTo("VTest")] exception. Cross-link to the ADR. - docs/futures/docs.md: removed the resolved "Decide whether to document VisioScripting as a public API" entry per the futures-> COMPLETED convention. - docs/COMPLETED.md: added a new Documentation subsection under Phase 3 with the full Resolution paragraph for the VisioScripting thread, covering the decision (#156), pre-lock cleanup (#182 Phase B + C via PR #185), dead-method stance (#184 Option A), gitbook write (#131), and the still-active CY27 tail (#183). - docs/FUTURES.md: index updated to drop the resolved item from the docs.md item list, with a one-liner pointer at COMPLETED.md. - CLAUDE.md: refreshed the "Repo state" line (master at #185 merge, CHANGELOG[Unreleased] now includes Phase B + C entries), labeled the prior session as "Previous session (2026-05-08b) summary" rather than "This session", added a new "This session (2026-05-09) summary" covering the five threads above, and replaced the "Next session priorities" body so the next session leads with #178 / #181 / #173 rather than the now-resolved #156. No code changes; no test impact. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 42 +++++++++---------- VisioAutomation_2010/VisioScripting/README.md | 22 ++++++---- docs/COMPLETED.md | 10 +++++ docs/FUTURES.md | 2 +- docs/futures/docs.md | 14 ------- 5 files changed, 47 insertions(+), 43 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 975947c9b..fd849ece0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -82,7 +82,7 @@ The first publish run surfaced several PSGallery / PS 5.1 gotchas (TLS 1.2 defau **Releases shipped this session:** **VisioAutomation NuGet 3.0.0** to nuget.org ([package page](https://www.nuget.org/packages/VisioAutomation2010/3.0.0)) — first end-to-end CI publish via the freshly-shipped `publish-nuget.yml`. Surfaced and worked around a Microsoft-package compliance gate on the saveenr account; SevenPens is now the canonical publisher for both NuGet and PSGallery. **Visio PowerShell 4.7.2** to PSGallery (already shipped; current). The CI release flow (`release-{psmodule,nuget}.yml` + `publish-{psmodule,nuget}.yml`) is fully operational. Detail in [`docs/futures/releases.md`](docs/futures/releases.md). -**Repo state:** master at HEAD (`b8710d96`). Working trees clean across all three primary repos (this repo + the two gitbook repos); 8 sibling repos each got a one-shot Phase H1 README commit during this session, `visio-templates` was deleted. The `experiment/linq-shapesheet` branch is on origin (1 commit, motivation doc only). PSGallery: `Visio` 4.7.2 live. NuGet: `VisioAutomation2010` 3.0.0 live. [`NuGet/CHANGELOG.md`](NuGet/CHANGELOG.md) `[Unreleased]` has the SevenPens brand-swap entry, the [#82](https://github.com/saveenr/VisioAutomation/issues/82) `MsaglRenderer.format_shape` fix, and the [#176](https://github.com/saveenr/VisioAutomation/issues/176) `` removal (all next-NuGet-release pickup); [`VisioPowerShell/CHANGELOG.md`](VisioAutomation_2010/VisioPowerShell/CHANGELOG.md) `[Unreleased]` has the SevenPens Author entry plus the [#177](https://github.com/saveenr/VisioAutomation/issues/177) Release-builds entry (next-PS-module-release pickup). +**Repo state:** master at HEAD (PR [#185](https://github.com/saveenr/VisioAutomation/pull/185) merged this session, bringing in [#182](https://github.com/saveenr/VisioAutomation/issues/182) Phase B + C plus the [#184](https://github.com/saveenr/VisioAutomation/issues/184) ADR update). Working trees clean across all three primary repos. The `experiment/linq-shapesheet` branch is on origin (1 commit, motivation doc only). PSGallery: `Visio` 4.7.2 live. NuGet: `VisioAutomation2010` 3.0.0 live. [`NuGet/CHANGELOG.md`](NuGet/CHANGELOG.md) `[Unreleased]` has the prior brand-swap / [#82](https://github.com/saveenr/VisioAutomation/issues/82) / [#176](https://github.com/saveenr/VisioAutomation/issues/176) entries plus this session's Added (4 facade methods on `Client`) and Removed (Loaders / `Get_*Dimensions` / Helpers / `CommandTarget` internalizations) blocks (all next-NuGet-release pickup); [`VisioPowerShell/CHANGELOG.md`](VisioAutomation_2010/VisioPowerShell/CHANGELOG.md) `[Unreleased]` carries the SevenPens Author entry plus the [#177](https://github.com/saveenr/VisioAutomation/issues/177) Release-builds entry (next-PS-module-release pickup). **Test infrastructure:** all four projects green — VTest 100/100, VTest.Models 64/64, VTest.Scripting 44/44, VTest.PowerShell 22/22. Total **230 tests** at runtime (226 enumerated by single-line `[TestMethod]` regex; +4 are multi-line attributes that the regex misses). Each test run still leaves zero Visio orphan processes. Naming convention now consistent across the suite (full rollout in this session per [#165](https://github.com/saveenr/VisioAutomation/issues/165)–[#169](https://github.com/saveenr/VisioAutomation/issues/169)); forward-looking convention codified in [`docs/TESTING.md`](docs/TESTING.md#naming-conventions). @@ -119,7 +119,7 @@ Test count: 211 enumerated → 226 enumerated (230 runtime). 8 commits to mas Plus filed [#170](https://github.com/saveenr/VisioAutomation/issues/170) for next session focus (LINQ provider for ShapeSheets). -**This session (2026-05-08b) summary:** Long working session, three major implementation threads plus broad backlog hygiene. +**Previous session (2026-05-08b) summary:** Long working session, three major implementation threads plus broad backlog hygiene. 1. **[#170](https://github.com/saveenr/VisioAutomation/issues/170) LINQ for ShapeSheet — motivation doc, spike deferred.** Rather than spike the implementation, drafted [`docs/futures/linq-shapesheet-before-after.md`](docs/futures/linq-shapesheet-before-after.md) (~250 lines) showing 9 ShapeSheet-query scenarios in today's API vs. a hypothetical LINQ shape, with an honest verdict per scenario (where LINQ wins, where it's a wash, where it may not fit). Doc closes with 7 design questions for whoever picks the spike up. Doc lives on the `experiment/linq-shapesheet` branch (commit `ac422911`, pushed to origin); spike code itself was deferred. **Issue [#170](https://github.com/saveenr/VisioAutomation/issues/170) rescoped from "LINQ provider for ShapeSheet queries" to "ShapeSheet query ergonomics (LINQ and other shapes)" and moved CY26Q2 → CY27Q1** at user request, since the user wanted to keep thinking about it (may yield non-LINQ ideas). @@ -137,36 +137,36 @@ Plus filed [#170](https://github.com/saveenr/VisioAutomation/issues/170) for nex 9 commits to master this session (`e4af7642` → `b8710d96`). 2 commits to .NET gitbook. 8 commits across the 8 sibling repos (one README each). 11 issues filed in main repo + 6 in sibling repos; 3 closed ([#152](https://github.com/saveenr/VisioAutomation/issues/152), [#176](https://github.com/saveenr/VisioAutomation/issues/176), [#177](https://github.com/saveenr/VisioAutomation/issues/177)). -## Next session priorities +**This session (2026-05-09) summary:** Long session focused end-to-end on the VisioScripting public-API thread, from decision through implementation through user-facing docs. + +1. **[#156](https://github.com/saveenr/VisioAutomation/issues/156) hybrid public-API decision (closed).** Walked Q1–Q4 (where's the line / how is it enforced / how do the boundary leaks resolve / cleanup precondition) and landed on **Hybrid**: `VisioScripting.Client` and the public method signatures on each `*Commands` class are public-stable; `Helpers/`, `Loaders/`, `CommandTarget`, `Get_*Dimensions` static factories stay internal-mutable. Filed [#182](https://github.com/saveenr/VisioAutomation/issues/182) (cleanup) and [#183](https://github.com/saveenr/VisioAutomation/issues/183) (CY27 dead-method removal) as follow-ups; [#184](https://github.com/saveenr/VisioAutomation/issues/184) for the dead-method-stance sub-question. -**Start next session with [#156](https://github.com/saveenr/VisioAutomation/issues/156) — Decide: is `VisioScripting` part of the project's promised public API, or an internal that shouldn't be relied on?** Decision-only issue (S effort) but the biggest single unblocker in the backlog: answering it directly unblocks [#131](https://github.com/saveenr/VisioAutomation/issues/131) (the largest remaining doc-write — `VisioScripting.Client` undocumented on gitbook) and shapes the strategy under [#172](https://github.com/saveenr/VisioAutomation/issues/172) (revise user-facing docs). +2. **[#182](https://github.com/saveenr/VisioAutomation/issues/182) Phase B + C implemented and merged via PR [#185](https://github.com/saveenr/VisioAutomation/pull/185).** Phase B added 4 facade methods (`Client.Model.LoadDirectedGraphFromXml`, `Client.Model.LoadOrgChartFromXml`, `Client.Page.GetPageDimensions`, `Client.Selection.GetShapeDimensions`) to close two boundary leaks; migrated 3 cmdlets ([`ImportVisioModel.cs`](VisioAutomation_2010/VisioPowerShell/Commands/VisioModel/ImportVisioModel.cs), [`MeasureVisioPage.cs`](VisioAutomation_2010/VisioPowerShell/Commands/VisioPage/MeasureVisioPage.cs), [`MeasureVisioShape.cs`](VisioAutomation_2010/VisioPowerShell/Commands/VisioShape/MeasureVisioShape.cs)) and 4 test calls; internalized the previously-leaked types/methods; dropped 2 unused `LoadFromXml(string)` overloads. Phase C internalized `Helpers/*` + `CommandTarget` + `CommandTargetFlags` + `Client.GetCommandTarget`; added `[InternalsVisibleTo("VTest")]` for one helper-unit-test reach-in. New ADR at [`docs/decisions/visioscripting-public-api.md`](docs/decisions/visioscripting-public-api.md). CLAUDE.md per-commit conventions section gained a code-review pointer at the contract. -**Background to load:** +3. **[#184](https://github.com/saveenr/VisioAutomation/issues/184) dead-method stance — Option A (closed).** Documented-but-dead methods carry "Remarks: candidate for CY27 removal (see [#183](https://github.com/saveenr/VisioAutomation/issues/183))" notes on their gitbook pages. Codebase will get `[Obsolete]` markings one minor release before the CY27 deletion. -- [`docs/futures/docs.md`](docs/futures/docs.md), entry "Decide whether to document `VisioScripting` as a public API" — framing of the question, current docs state (just `Get-VisioClient` + two technical-notes pages), surface-size estimate (~15 helper/command-set pages, similar to the .NET-side Tier 1+2+4 work already shipped). -- The codebase: [`VisioAutomation_2010/VisioScripting/`](VisioAutomation_2010/VisioScripting/) — particularly the `Client` object grouping commands by topic (`Document`, `Page`, `Selection`, `Shape`, `ShapeSheet`, `CustomProperty`, etc., ~22 groups). -- The PS-side escape hatches today: `cmdlets/other-cmdlets.md`'s `Get-VisioClient`; `technical-notes/getting-the-current-scriptingsession.md`; `technical-notes/use-visioautomation.md`. -- 2026-05-05 doc-review feedback noted in `docs/futures/docs.md`: the source [`readme.md`](readme.md)'s quick-start opens with a `VisioScripting.Client` snippet, so a new C# reader's first impression is an undocumented type. Strongest external argument for "yes, public." +4. **[#131](https://github.com/saveenr/VisioAutomation/issues/131) doc-write closed.** New `## VisioScripting` section on [VisioAutomation gitbook](https://saveenr.gitbook.io/visioautomation/visio-scripting): overview page + 25 per-group sub-pages, one per `*Commands` class. Pages with dead methods carry a `## Removal candidates (CY27)` section per [#184](https://github.com/saveenr/VisioAutomation/issues/184). [`getting-started.md`](https://saveenr.gitbook.io/visioautomation/readme/getting-started)'s API-selection table now links the `VisioScripting.Client` row at the new overview. PSGallery cross-links: 15 cmdlet topic READMEs on [VisioPowerShellDocs](https://saveenr.gitbook.io/visiopowershell/) gain a `## On the C# side` section pointing at the corresponding `client.` page. -**Decision shape — three plausible answers:** +5. **End-of-session cleanup.** Updated [`VisioScripting/README.md`](VisioAutomation_2010/VisioScripting/README.md) post-Phase-C (CommandTarget / Loaders flagged as internal). Pruned the resolved item from [`docs/futures/docs.md`](docs/futures/docs.md), added the Resolution to [`docs/COMPLETED.md`](docs/COMPLETED.md), updated [`docs/FUTURES.md`](docs/FUTURES.md) cross-ref. CLAUDE.md "Current state" + "Next session priorities" sections refreshed. -1. **Yes, public API.** Document the full surface (~15 pages); commit to API stability; no more "shifts to suit cmdlet needs" without thinking about external consumers. -2. **No, internal.** Leave undocumented; fix `readme.md`'s quick-start to use `VisioAutomation` directly; close [#131](https://github.com/saveenr/VisioAutomation/issues/131) as won't-fix; mark types `[EditorBrowsable(Never)]` or similar. -3. **Hybrid.** Document `Client..(...)` *interface* as public-stable; leave implementation classes (`*Commands`, `*Loaders`) undocumented as still-mutable internals. +Issues closed: [#156](https://github.com/saveenr/VisioAutomation/issues/156), [#182](https://github.com/saveenr/VisioAutomation/issues/182), [#184](https://github.com/saveenr/VisioAutomation/issues/184), [#131](https://github.com/saveenr/VisioAutomation/issues/131). Issues filed: [#182](https://github.com/saveenr/VisioAutomation/issues/182), [#183](https://github.com/saveenr/VisioAutomation/issues/183), [#184](https://github.com/saveenr/VisioAutomation/issues/184). Code: 3 commits to master via PR [#185](https://github.com/saveenr/VisioAutomation/pull/185), plus 1 cleanup commit. Docs: 5 commits to .NET gitbook, 1 commit to PSGallery docs. + +## Next session priorities -Each answer changes the work scope for [#131](https://github.com/saveenr/VisioAutomation/issues/131) and shapes [#157](https://github.com/saveenr/VisioAutomation/issues/157) (long-term docs location). It also touches [#162](https://github.com/saveenr/VisioAutomation/issues/162) (PSVA Phase A scoping) and [#164](https://github.com/saveenr/VisioAutomation/issues/164) (VisioCmdlet base class) since both can shift the cmdlet/Scripting boundary. +The VisioScripting public-API thread closed end-to-end this session. Next obvious items, all CY26Q3, all S–M effort: -**Acceptance:** comment on [#156](https://github.com/saveenr/VisioAutomation/issues/156) with the decision, one-paragraph rationale, and a brief "implications for #131, #172, #157" bullet. Close [#156](https://github.com/saveenr/VisioAutomation/issues/156). +- **[#178](https://github.com/saveenr/VisioAutomation/issues/178)** finish `Visio.psd1` deprecation cleanup (RootModule rename + PowerShellVersion bump). Customer-impact analysis pre-done; one-line edits. ~15 min. +- **[#181](https://github.com/saveenr/VisioAutomation/issues/181)** mirror [#177](https://github.com/saveenr/VisioAutomation/issues/177) for the NuGet release flow (release-nuget.yml + nuspec). Same pattern, same effort. ~30 min. +- **[#173](https://github.com/saveenr/VisioAutomation/issues/173)** cmdlet-binding test first slice. Closes the regression class that shipped 4.6.1's four bugs. Wider effort; "first slice" is a bounded chunk. -**Lower priority same semester** (CY26Q2 is in close-out mode): +**Calendar-bound:** -- **[#151](https://github.com/saveenr/VisioAutomation/issues/151) triage tracker** — calendar-bound. Revisit ~2026-05-27: if `@tcox8` hasn't confirmed [Visio PS 4.7.0](https://github.com/saveenr/VisioAutomation/releases/tag/VisioPS_4.7.0) fixed their case by then, close [#117](https://github.com/saveenr/VisioAutomation/issues/117) as fixed-by-#144 then close [#151](https://github.com/saveenr/VisioAutomation/issues/151). +- **[#151](https://github.com/saveenr/VisioAutomation/issues/151)** triage tracker — revisit ~2026-05-27. If `@tcox8` hasn't confirmed [Visio PS 4.7.0](https://github.com/saveenr/VisioAutomation/releases/tag/VisioPS_4.7.0) fixed their case by then, close [#117](https://github.com/saveenr/VisioAutomation/issues/117) as fixed-by-[#144](https://github.com/saveenr/VisioAutomation/issues/144) then close [#151](https://github.com/saveenr/VisioAutomation/issues/151). -**Quick-pickup follow-ups if bandwidth permits** (all CY26Q3, all S–M effort): +**Longer-term:** -- **[#178](https://github.com/saveenr/VisioAutomation/issues/178)** finish `Visio.psd1` deprecation cleanup (RootModule rename + PowerShellVersion bump). Customer-impact analysis pre-done; one-line edits. -- **[#181](https://github.com/saveenr/VisioAutomation/issues/181)** mirror [#177](https://github.com/saveenr/VisioAutomation/issues/177) for the NuGet release flow (release-nuget.yml + nuspec). Same pattern, same effort. -- **[#173](https://github.com/saveenr/VisioAutomation/issues/173)** cmdlet-binding test first slice. Closes the regression class that shipped 4.6.1's four bugs. +- **[#183](https://github.com/saveenr/VisioAutomation/issues/183)** CY27Q1 dead-method removal (Phase A of the VisioScripting public-API work). Audit list preserved on the issue body; re-verify zero-callers immediately before deletion since usage may have developed between now and CY27. +- Other CY26Q3 / CY26Q4 backlog items: see [`docs/MILESTONES.md`](docs/MILESTONES.md). ## Other docs in this repo diff --git a/VisioAutomation_2010/VisioScripting/README.md b/VisioAutomation_2010/VisioScripting/README.md index 03ed64c9c..963ceba08 100644 --- a/VisioAutomation_2010/VisioScripting/README.md +++ b/VisioAutomation_2010/VisioScripting/README.md @@ -15,20 +15,28 @@ client.Draw.DrawRectangle(TargetPage.Auto, new Rectangle(0, 0, 4, 2)); client.Text.SetText(TargetShapes.Auto, "Hello"); ``` -## Key types +## Public-API contract -- [`Client`](Client.cs) — entry point, constructed with an `IVisio.Application`. Exposes command groups as properties (`Application`, `Document`, `Page`, `Selection`, `Draw`, `Text`, `Arrange`, `Connection`, `ShapeSheet`, `Layer`, `Grouping`, `Master`, `CustomProperty`, `Hyperlink`, `Control`, …). +The hybrid public-API contract from [`docs/decisions/visioscripting-public-api.md`](../../docs/decisions/visioscripting-public-api.md) is the source of truth for what's public-stable vs internal-mutable. User-facing reference docs are on the gitbook at . + +## Public-stable types + +- [`Client`](Client.cs) — entry point, constructed with an `IVisio.Application`. Exposes 25 command groups as properties (`Application`, `Document`, `Page`, `Selection`, `Draw`, `Text`, `Arrange`, `Connection`, `ShapeSheet`, `Layer`, `Grouping`, `Master`, `CustomProperty`, `Hyperlink`, `Control`, …). - [`ClientContext`](ClientContext.cs) — abstract output sink (`WriteDebug` / `WriteUser` / `WriteError` / `WriteVerbose` / `WriteWarning`). Subclass to redirect logging. - [`DefaultClientContext`](DefaultClientContext.cs) — concrete `ClientContext` that writes to `Console`. -- [`CommandTarget`](CommandTarget.cs) + [`CommandTargetFlags`](CommandTargetFlags.cs) — preconditions wrapper. A command declares it needs (e.g.) an active page; `CommandTarget` validates and resolves that state up front. - `Target*` family — deferred-resolution wrappers ([`TargetDocument`](TargetDocument.cs), [`TargetPage`](TargetPage.cs), [`TargetShapes`](TargetShapes.cs), [`TargetSelection`](TargetSelection.cs), [`TargetWindow`](TargetWindow.cs), `TargetPages`, `TargetDocuments`, `TargetObject`, `TargetObjects`). `TargetPage.Auto` means *"use the active page when this command runs"* — keeps callers from having to fetch and pass COM objects explicitly. +## Internal plumbing (free to change without notice) + +- [`CommandTarget`](CommandTarget.cs) + [`CommandTargetFlags`](CommandTargetFlags.cs) — preconditions wrapper. A command declares it needs (e.g.) an active page; `CommandTarget` validates and resolves that state up front. Reached only from inside `*Commands` method bodies. +- `Helpers/`, `Loaders/`, `Models.*Dimensions.Get_*Dimensions` — see *Folder layout* below. + ## Folder layout -- `Commands/` — verb-noun command groups, one file per group. `ApplicationCommands`, `DocumentCommands`, `PageCommands`, `DrawCommands`, `SelectionCommands`, `TextCommands`, `ShapeSheetCommands`, `ArrangeCommands`, `ConnectionCommands`, `ConnectionPointCommands`, `ContainerrCommands`, `ControlCommands`, `CustomPropertyCommands`, `DeveloperCommands`, `ExportCommands`, `GroupingCommands`, `HyperlinkCommands`, `LayerCommands`, `LockCommands`, `MasterCommands`, `ModelCommands`, `OutputCommands`, `UndoCommands`, `UserDefinedCellCommands`, `ViewCommands`. Plus `Command.cs`/`CommandParameter.cs`/`CommandSet.cs` (base types). -- `Models/` — small enums and value types used as command parameters and return values (`AlignmentHorizontal`, `AlignmentVertical`, `Axis`, `ConnectionPointType`, `PageDimensions`, `PageOrientation`, `SelectionOperation`, `ShapeDimensions`, …). -- `Helpers/` — internal helpers shared across command groups (`ArrangeHelper`, `InteropHelper`, `ReflectionHelper`, `SelectionHelper`, `TextHelper`, `WildcardHelper`). -- `Loaders/` — turn-key loaders for higher-level documents (`DirectedGraphDocumentLoader`, `OrgChartDocumentLoader`). +- `Commands/` — verb-noun command groups, one file per group. `ApplicationCommands`, `DocumentCommands`, `PageCommands`, `DrawCommands`, `SelectionCommands`, `TextCommands`, `ShapeSheetCommands`, `ArrangeCommands`, `ConnectionCommands`, `ConnectionPointCommands`, `ContainerrCommands`, `ControlCommands`, `CustomPropertyCommands`, `DeveloperCommands`, `ExportCommands`, `GroupingCommands`, `HyperlinkCommands`, `LayerCommands`, `LockCommands`, `MasterCommands`, `ModelCommands`, `OutputCommands`, `UndoCommands`, `UserDefinedCellCommands`, `ViewCommands`. Plus `Command.cs`/`CommandParameter.cs`/`CommandSet.cs` (base types). The classes are public (they're the return types of `Client.Page` etc.) but their constructors are `internal`; obtain instances via `Client.`, never `new`. +- `Models/` — small enums and value types used as command parameters and return values (`AlignmentHorizontal`, `AlignmentVertical`, `Axis`, `ConnectionPointType`, `PageDimensions`, `PageOrientation`, `SelectionOperation`, `ShapeDimensions`, …). Types referenced from public method signatures are part of the public-stable contract; types not in any public signature (`DgShapeInfo`, `DgConnectorInfo`) are `internal`. +- `Helpers/` — internal helpers shared across command groups (`ArrangeHelper`, `InteropHelper`, `ReflectionHelper`, `SelectionHelper`, `TextHelper`, `WildcardHelper`). All `internal`. `[InternalsVisibleTo("VTest")]` lets one helper-unit-test reach in directly. +- `Loaders/` — `internal` parsers for higher-level model documents (`DirectedGraphDocumentLoader`, `OrgChartDocumentLoader`). Reached publicly through `Client.Model.LoadDirectedGraphFromXml(XDocument)` / `Client.Model.LoadOrgChartFromXml(XDocument)`. - `Extensions/` — extension methods used internally (`XmlLinqExtensions`). ## See also diff --git a/docs/COMPLETED.md b/docs/COMPLETED.md index 80b388fd7..27dbaab5c 100644 --- a/docs/COMPLETED.md +++ b/docs/COMPLETED.md @@ -99,3 +99,13 @@ Headline summary in [`ROADMAP.md`](ROADMAP.md#phase-3--modernization-in-progress - **What:** None of the four test projects had READMEs explaining what they cover, what fixtures they need, or what state they assume Visio to be in. The shared infrastructure (`Framework.VTest` base class, per-testhost Visio singleton, `[AssemblyCleanup]` orphan-prevention) had no top-level documentation. - **Resolution (`a41e97bc`):** Added per-project `README.md` for [`VTest/`](../VisioAutomation_2010/VTest/README.md), [`VTest.Models/`](../VisioAutomation_2010/VTest.Models/README.md), [`VTest.Scripting/`](../VisioAutomation_2010/VTest.Scripting/README.md), and [`VTest.PowerShell/`](../VisioAutomation_2010/VTest.PowerShell/README.md). Added top-level [`docs/TESTING.md`](TESTING.md) covering the test-suite design (the three load-bearing constraints: real Visio, sequential execution, per-testhost singleton); shared infrastructure (`Framework.VTest`, `VTestAppRef`, `[AssemblyCleanup]` per-assembly pattern, datafiles convention); MSTest.Analyzers + MSTEST0030 enforcement; how-to-run pointers; and known gotchas. Cross-linked from `CLAUDE.md` and `docs/OVERVIEW.md`. - **Tail (still active in the backlog):** The *coverage-gaps* angle of the original "General cleanup of the test projects" entry was deliberately not bundled with this work; deferred indefinitely as too open-ended to scope. Tracked under *Test coverage gaps* in [`futures/tests.md`](futures/tests.md#test-coverage-gaps). + +### Documentation + +#### Decide whether to document `VisioScripting` as a public API (and document it) +- **What:** Decision item: is `VisioScripting` part of the project's promised surface, or an internal that shouldn't be relied on? Surfaced by the 2026-05-05 doc-review pass as the single highest-priority documentation hole, since the source `readme.md` quick-start opens with a `VisioScripting.Client` snippet so a new C# reader's first impression was an undocumented type. +- **Resolution (2026-05-09):** **Hybrid public** ([#156](https://github.com/saveenr/VisioAutomation/issues/156)). `VisioScripting.Client` and the public method signatures on each `*Commands` class are public-stable; `Helpers/`, `Loaders/`, `CommandTarget`, and other plumbing stay internal-mutable. ADR captured at [`docs/decisions/visioscripting-public-api.md`](decisions/visioscripting-public-api.md). + - **Pre-lock cleanup ([#182](https://github.com/saveenr/VisioAutomation/issues/182), Phases B + C):** Phase B added 4 facade methods (`Client.Model.LoadDirectedGraphFromXml`, `Client.Model.LoadOrgChartFromXml`, `Client.Page.GetPageDimensions`, `Client.Selection.GetShapeDimensions`) to close two boundary leaks where cmdlets had been reaching past `Client` into `VisioScripting.Loaders.*` and `VisioScripting.Models.*Dimensions.Get_*`. Migrated 3 cmdlets and 4 test calls to the new facade methods. Internalized the previously-leaked types/methods. Phase C applied the layered enforcement: `Helpers/*`, `CommandTarget`, `CommandTargetFlags`, and `Client.GetCommandTarget` flipped to `internal`; `[InternalsVisibleTo("VTest")]` for one helper-unit-test reach-in. + - **Doc-write ([#131](https://github.com/saveenr/VisioAutomation/issues/131)):** Shipped a top-level `## VisioScripting` section on the `VisioAutomation_GitBook_Docs` gitbook with an [overview page](https://saveenr.gitbook.io/visioautomation/visio-scripting) plus 25 per-group sub-pages (one per `*Commands` class). The `getting-started.md` API-selection table now links the `VisioScripting.Client` row at the new overview. PowerShell-side cross-links added in `VisioPowerShellDocs`: 15 cmdlet topic READMEs gain a `## On the C# side` section pointing at the corresponding `client.` page. + - **Dead-method-stance sub-question ([#184](https://github.com/saveenr/VisioAutomation/issues/184)):** Resolved Option A. The ~36 dead methods identified by the pre-decision usage audit are part of the locked surface; their gitbook pages carry "Remarks: candidate for CY27 removal (see #183)" notes. Codebase will get `[Obsolete]` attributes one minor release before deletion. +- **Tail (still active in the backlog):** Phase A of the cleanup, removing the ~36 dead methods + the dead `LayerCommands` class + 4 dead `OutputCommands` methods + the `ContainerrCommands.cs` filename typo, is deferred to CY27 per the project's "improve before audience-reducing changes" guiding principle. Tracked under [#183](https://github.com/saveenr/VisioAutomation/issues/183) in the CY27Q1 milestone. diff --git a/docs/FUTURES.md b/docs/FUTURES.md index f7093947a..a39ef43b5 100644 --- a/docs/FUTURES.md +++ b/docs/FUTURES.md @@ -13,5 +13,5 @@ A running list of cleanup, modernization, and improvement items for the VisioAut - **[`futures/build-and-code.md`](futures/build-and-code.md)** — Build & tooling, Code & architecture. Items: *Consolidate target frameworks*, *Run tests in CI*, *Move development to Visual Studio 2026*, *Consider migrating off Visio 2010 PIA*, *Move to C# 14 / .NET 10*, *Make `CustomPropertyCells` values not require manual `EncodeValues()`*, *Borrow ideas from VisioBot3000 for VisioPS ergonomics*, *Borrow ideas from PSVA for VisioPS bulk-operation cmdlets*, *Evaluate NetOffice / NetOfficeFw as a replacement for the Visio PIA*, *Move `LinqExtensions` out of `Internal/`*. - **[`futures/tests.md`](futures/tests.md)** — Test-related items. Items: *Tests require a live Visio* (design decision), *Test coverage gaps* (audit output in [`futures/test-coverage-gaps.md`](futures/test-coverage-gaps.md)), *Evaluate modern testing-stack options*. - **[`futures/releases.md`](futures/releases.md)** — Release process and version policy. Items: *Reconcile version numbers across artifacts*, *Switch module-release builds from Debug to Release*, *Address `Visio.psd1` deprecation warnings on PSGallery publish*, *Automate releases via GitHub CI*. -- **[`futures/docs.md`](futures/docs.md)** — Documentation items, in-repo and user-facing gitbook. Items: *Decide where docs live long-term*, *Restructure the user-docs repos*, *Decide whether to document `VisioScripting` as a public API*, *Keep CHANGELOGs current*, *Add a troubleshooting page to the .NET gitbook*, *Revise user-facing documentation for accuracy*. +- **[`futures/docs.md`](futures/docs.md)** — Documentation items, in-repo and user-facing gitbook. Items: *Decide where docs live long-term*, *Restructure the user-docs repos*, *Keep CHANGELOGs current*, *Add a troubleshooting page to the .NET gitbook*, *Revise user-facing documentation for accuracy*. (*Decide whether to document `VisioScripting` as a public API* resolved 2026-05-09 ([#156](https://github.com/saveenr/VisioAutomation/issues/156)) and documented ([#131](https://github.com/saveenr/VisioAutomation/issues/131)); see [`COMPLETED.md`](COMPLETED.md#decide-whether-to-document-visioscripting-as-a-public-api-and-document-it).) - **[`futures/identity.md`](futures/identity.md)** — Dev team identity. Items: *Transition dev team identity from "Saveen" to "SevenPens"* (9 axes total; axes 1, 2, 3, 4, 6, 7, 8 done as of 2026-05-07. Axis 5 (hosting URLs) tracked in [#146](https://github.com/saveenr/VisioAutomation/issues/146) + [#147](https://github.com/saveenr/VisioAutomation/issues/147), scheduled `CY26Q4` milestone. Axis 9 (retire unused VisioAutomation legacy account) tracked in [#148](https://github.com/saveenr/VisioAutomation/issues/148), unscheduled). diff --git a/docs/futures/docs.md b/docs/futures/docs.md index d271bdbcb..c72e2fe6e 100644 --- a/docs/futures/docs.md +++ b/docs/futures/docs.md @@ -50,20 +50,6 @@ Backlog of documentation items, both in-repo developer docs and the user-facing - M for option 3 or option 2 (half a day to a full day). - N/A (no work) for option 1. -### Decide whether to document `VisioScripting` as a public API -- **What:** `VisioScripting` is the .NET layer between the PowerShell cmdlets and the underlying `VisioAutomation` library. Its `Client` object groups commands by topic (`Document`, `Page`, `Selection`, `View`, `Text`, `Shape`, `ShapeSheet`, `Application`, `Master`, `Container`, `Connection`, `Hyperlink`, `Lock`, `CustomProperty`, `UserDefinedCell`, `Output`, `Undo`, `Window`, `Layer`, `Color`, etc.) — most cmdlets are thin wrappers over a `Client..(...)` call. -- **External feedback (2026-05-05):** A doc-review pass on the gitbook ([proposed-issues.md issue #1](https://github.com/saveenr/VisioAutomation_GitBook_Docs/blob/main/proposed-issues.md), since converted into a GitHub issue) flagged the `VisioScripting` gap as the single highest-priority documentation hole. The argument: the source [`readme.md`](../../readme.md) leads with a `VisioScripting.Client` snippet as its quick-start, so a new C# reader's *first impression* is an undocumented type. That moves the open question below ("part of the project's promised surface, or internal?") from theoretical to forcing-function — answer it before deciding whether to fill the gap. -- **Currently documented:** only as power-user escape hatches. The PS-side `cmdlets/other-cmdlets.md` lists `Get-VisioClient` (which returns a `VisioScripting.Client`); `technical-notes/getting-the-current-scriptingsession.md` and `technical-notes/use-visioautomation.md` give brief pointers to the .NET-side bridge. There is no per-method or per-group reference for `VisioScripting` itself. -- **Why this is a real question, not just a coverage gap:** - - **Audience.** `VisioScripting` is a *higher-level* alternative to the raw `VisioAutomation` library — you'd reach for it from .NET when you want commands like "duplicate this page" or "select all shapes" without composing them yourself from `Page.Pages.Add` + `ShapeSheet.Writers.SrcWriter` + ... . That's a real audience, separate from PowerShell users. - - **Stability.** Right now `VisioScripting` is treated as an internal implementation detail of the cmdlets — APIs may shift to suit cmdlet needs. Documenting it elevates it to a public surface, which changes the cost of API churn. - - **Surface size.** Roughly one Helper / Commands class per topic, each with 5–20 methods. Order-of-magnitude similar to the .NET-side Tier 1+2+4 work that was just done (~15 pages). -- **Decisions to make first:** - - **Is `VisioScripting` part of the project's promised surface, or an internal that shouldn't be relied on?** Affects whether documentation should exist at all and whether the cmdlets should keep wrapping it. - - **Same gitbook or separate?** Could be a third gitbook, or a section under [VisioAutomation_GitBook_Docs](https://github.com/saveenr/VisioAutomation_GitBook_Docs). -- **Cross-refs:** *Decide where docs live long-term* (related policy question). The recently-completed Tiers 1+2+4 .NET-side coverage work is the validated pattern this would follow. -- **Effort:** S to decide. M–L to write if the answer is "yes, document it" (similar in size to Tiers 1+2+4 of the .NET-side coverage). - ### Keep CHANGELOGs current as Phase 1 work lands - **What:** Two changelogs were added in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format: [`NuGet/CHANGELOG.md`](../../NuGet/CHANGELOG.md) for the `VisioAutomation2010` NuGet, and [`VisioAutomation_2010/VisioPowerShell/CHANGELOG.md`](../../VisioAutomation_2010/VisioPowerShell/CHANGELOG.md) for the `Visio` PowerShell module. Each has an `[Unreleased]` section that should accumulate consumer-visible changes until the Phase 2 release cuts a real version. - **Why:** The whole point of cutting a final release in Phase 2 is to give consumers a clean, well-documented checkpoint. If Unreleased sections drift behind reality during Phase 1, the release notes will be wrong.