Skip to content

docs: cleanup pass after the VisioScripting public-API thread #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheSevenPens merged 1 commit into from
May 9, 2026
Merged

docs: cleanup pass after the VisioScripting public-API thread #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) `<frameworkAssembly>` 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 &mdash; 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)&ndash;[#169](https://github.com/saveenr/VisioAutomation/issues/169)); forward-looking convention codified in [`docs/TESTING.md`](docs/TESTING.md#naming-conventions).

Expand Down Expand Up @@ -119,7 +119,7 @@ Test count: 211 enumerated &rarr; 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 &mdash; 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 &rarr; CY27Q1** at user request, since the user wanted to keep thinking about it (may yield non-LINQ ideas).

Expand All @@ -137,36 +137,36 @@ Plus filed [#170](https://github.com/saveenr/VisioAutomation/issues/170) for nex

9 commits to master this session (`e4af7642` &rarr; `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&ndash;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) &mdash; 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 &mdash; `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 &mdash; 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" &mdash; 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/) &mdash; 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.<Group>` page.

**Decision shape &mdash; 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.<Group>.<Method>(...)` *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&ndash;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** &mdash; 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 &mdash; 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&ndash;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

Expand Down
Loading
Loading