VisioScripting public-API pre-lock cleanup (Phases B + C)

[saveenr]

Actionable follow-up to the hybrid-public-API decision in #156. This issue covers the pre-lock cleanup that must land before #131 starts the gitbook write-up.

Scope

Two phases. Phase A (dead-method removal) is deferred to CY27 per the project's "improve before audience-reducing changes" guiding principle, tracked separately.

Phase B — Boundary-leak facade methods

The audit under #156 found two cmdlet patterns that bypass the Client facade. Add facade methods, migrate consumers, internalize the previously-leaked types/methods.

Loaders leak (VisioScripting.Loaders.*.LoadFromXml(...)):

• Add Client.Model.LoadDirectedGraphFromXml(XDocument) returning DirectedGraphDocument
• Add Client.Model.LoadOrgChartFromXml(XDocument) returning OrgChartDocument
• Migrate ImportVisioModel.cs to call the new facade methods
• Migrate the 2 tests in VTest.Models/ that call DirectedGraphDocumentLoader.LoadFromXml(...) / OrgChartDocumentLoader.LoadFromXml(...) directly
• Mark DirectedGraphDocumentLoader and OrgChartDocumentLoader internal
• Drop the unused LoadFromXml(client, string filename) overload on DirectedGraphDocumentLoader (no external caller)

Dimensions leak (VisioScripting.Models.*Dimensions.Get_*Dimensions(...)):

• Add Client.Page.GetPageDimensions(TargetPages) returning List<Models.PageDimensions>
• Add Client.Selection.GetShapeDimensions(TargetShapes) returning List<Models.ShapeDimensions> (placement-of-convenience; a dedicated ShapeCommands is a larger architectural question, deferred)
• Migrate MeasureVisioPage.cs and MeasureVisioShape.cs
• Mark the static factory methods internal. Keep the PageDimensions / ShapeDimensions types public (they are return values)

Phase C — Enforcement layer

Apply the layered enforcement strategy from #156 Q2.

• Mark VisioScripting.Helpers/* types internal (5 files: ArrangeHelper, InteropHelper, ReflectionHelper, SelectionHelper, TextHelper, WildcardHelper). Add [InternalsVisibleTo(...)] for VisioPowerShell and the four test projects (VTest, VTest.Models, VTest.Scripting, VTest.PowerShell). Relocate the one external test of WildcardHelper to VTest's internal-test scope or use the InternalsVisibleTo path
• Mark CommandTarget and CommandTargetFlags internal
• Mark Client.GetCommandTarget(flags) either internal or, if that breaks the *Commands plumbing, public with [EditorBrowsable(Never)] and an XML doc comment
• Sweep VisioScripting.Models/* for any types not appearing in any public signature, mark them internal
• Add [EditorBrowsable(Never)] + XML doc comments to any types that have to stay public for signature reasons but are not part of the contract
• Write ADR at docs/decisions/visioscripting-public-api.md capturing the hybrid contract — what is in, what is out, the enforcement layers, and the rationale (point at the #156 decision comment)
• Add a paragraph to CLAUDE.md per-commit conventions section noting that public surface changes on VisioScripting.Client / *Commands classes are breaking changes

Out of scope

• Phase A — dead-method removal. ~36 unused public methods + dead LayerCommands class + 4 unused OutputCommands methods + ContainerrCommands.cs filename typo. Tracked in the CY27 follow-up issue (filed alongside this one).
• PublicAPI.Shipped.txt analyzer. Deferred per #156 Q2; can be added later if drift becomes a real problem.
• Architectural question "should there be a ShapeCommands class?" Deferred.

Acceptance

• All Phase B and Phase C task-list items above checked off
• Build clean across the solution
• All 230 tests still pass
• ADR landed
• CLAUDE.md updated

Blocks

• #131 (document VisioScripting.Client on gitbook). After this lands, #131 writes against the locked surface.

References

• Decision and rationale: #156 closing comment
• Usage audit findings (informs the *Commands placements for new facade methods): #156 discussion thread

Effort

M. ~9 hours total: Phase B ~6h, Phase C ~3h. Separable into two PRs if convenient.

[saveenr]

Phase B + Phase C both landed. Closing.

What shipped

Phase B (c8bcabcc) — boundary-leak facade methods:

• 4 new facade methods on Client: Client.Model.LoadDirectedGraphFromXml(XDocument), Client.Model.LoadOrgChartFromXml(XDocument), Client.Page.GetPageDimensions(TargetPages), Client.Selection.GetShapeDimensions(TargetShapes).
• Migrated 3 cmdlets (ImportVisioModel, MeasureVisioPage, MeasureVisioShape) and 4 test calls (3 in DirectedGraphDrawModelTests, 1 in OrgChartDrawModelTests) to the new facade methods.
• Marked the previously-leaked types/methods internal: DirectedGraphDocumentLoader, OrgChartDocumentLoader (whole class), PageDimensions.Get_PageDimensions, ShapeDimensions.Get_ShapeDimensions (static factory methods only — data classes stay public).
• Dropped the unused LoadFromXml(client, string filename) overloads on both loaders.

Phase C (30dd4dff) — enforcement layer:

• Helpers/* internalized: WildcardHelper, InteropHelper, SelectionHelper flipped to internal (the other three were already internal).
• CommandTarget, CommandTargetFlags, Client.GetCommandTarget(...) all flipped to internal.
• [InternalsVisibleTo("VTest")] added to VisioScripting for the one helper-unit-test reach-in. None of VisioPowerShell, VTest.Models, VTest.Scripting, or VTest.PowerShell needed access; future reach-ins should add their own InternalsVisibleTo lines rather than expanding this one.
• Models sweep produced no changes today (the obvious internal candidates DgShapeInfo / DgConnectorInfo were already internal; the rest are pinned public either by appearing in active public signatures or by pinning to dead-but-staying-public methods deferred to #183).
• New ADR at docs/decisions/visioscripting-public-api.md.
• CLAUDE.md per-commit conventions section gains a pointer at the ADR with the actionable summary for code review.

Verification

• Build clean across the 11-project solution.
• All 230 tests pass (VTest 100, VTest.Models 64, VTest.Scripting 44, VTest.PowerShell 22). ~2-minute run, zero Visio orphan processes.
• Post-sweep grep confirms the now-internal surface is reachable only from inside the VisioScripting assembly.

What's next

• #131 (document VisioScripting.Client on gitbook) is now unblocked. Header on that issue updated.
• #184 (dead-method-stance decision) still needs to be answered before per-page templates start in #131.
• #183 (CY27 dead-method removal — Phase A) waits.