refactor(scripting): hybrid public-API pre-lock cleanup (#182)

CLAUDE.md

@@ -44,6 +44,7 @@ All test projects exercise real Visio COM calls. There is no mock/fake layer (in
 ## Per-commit conventions
 
 - **Changelogs:** when a change is consumer-visible (public API, behavior, supported runtime, dependencies) add an entry to the matching `[Unreleased]` section of [`NuGet/CHANGELOG.md`](NuGet/CHANGELOG.md) or [`VisioAutomation_2010/VisioPowerShell/CHANGELOG.md`](VisioAutomation_2010/VisioPowerShell/CHANGELOG.md) in the **same commit**. Pure internal / build / docs changes don't need entries.
+- **`VisioScripting` public-API contract:** the `Client` facade and the public method signatures on each `*Commands` class are public-stable per [`docs/decisions/visioscripting-public-api.md`](docs/decisions/visioscripting-public-api.md). **Renaming or removing** a public method on `Client` or any `*Commands` class is a **breaking change** — treat it accordingly. Adding methods is non-breaking. The plumbing (`Helpers/`, `Loaders/`, `CommandTarget`, `CommandTargetFlags`, `Get_*Dimensions` static factories) is `internal` and free to change without notice. When the line is unclear, the ADR has the authoritative table.
 - **PowerShell loader scripts** in `VisioAutomation_2010/VisioPowerShell/`: `Load*` does in-session imports; `Install*` does persistent installs to the user's PS modules folder; `*.ISE.ps1` is the ISE-launched variant. See the folder's [README.md](VisioAutomation_2010/VisioPowerShell/README.md).
 
 ## Tooling notes

NuGet/CHANGELOG.md

@@ -12,6 +12,21 @@ The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/
 
 ## [Unreleased]
 
+### Added
+- New facade methods on `VisioScripting.Client` for operations that previously required reaching past the facade. These are the canonical entry points going forward and align with the hybrid public-API contract decided in [#156](https://github.com/saveenr/VisioAutomation/issues/156):
+  - `Client.Model.LoadDirectedGraphFromXml(XDocument)` returns a `DirectedGraphDocument` (replaces `DirectedGraphDocumentLoader.LoadFromXml`).
+  - `Client.Model.LoadOrgChartFromXml(XDocument)` returns an `OrgChartDocument` (replaces `OrgChartDocumentLoader.LoadFromXml`).
+  - `Client.Page.GetPageDimensions(TargetPages)` returns `List<PageDimensions>` (replaces the static `PageDimensions.Get_PageDimensions`).
+  - `Client.Selection.GetShapeDimensions(TargetShapes)` returns `List<ShapeDimensions>` (replaces the static `ShapeDimensions.Get_ShapeDimensions`).
+
+  Part of [#182](https://github.com/saveenr/VisioAutomation/issues/182).
+
+### Removed
+- `VisioScripting.Loaders.DirectedGraphDocumentLoader` and `VisioScripting.Loaders.OrgChartDocumentLoader` are now `internal`. Direct consumers should switch to `Client.Model.LoadDirectedGraphFromXml` / `Client.Model.LoadOrgChartFromXml`. Part of [#182](https://github.com/saveenr/VisioAutomation/issues/182).
+- Static `Get_PageDimensions` / `Get_ShapeDimensions` factory methods on `VisioScripting.Models.PageDimensions` / `Models.ShapeDimensions` are now `internal`. Use `Client.Page.GetPageDimensions` / `Client.Selection.GetShapeDimensions` instead. The data-carrier types themselves remain `public` (they are return values). Part of [#182](https://github.com/saveenr/VisioAutomation/issues/182).
+- Unused `LoadFromXml(Client, string filename)` overloads on both `DirectedGraphDocumentLoader` and `OrgChartDocumentLoader`. Each was an internal convenience that loaded the XML file and deferred to the `XDocument` overload; no external caller ever invoked them. Part of [#182](https://github.com/saveenr/VisioAutomation/issues/182).
+- The plumbing types `VisioScripting.CommandTarget`, `VisioScripting.CommandTargetFlags`, and `Client.GetCommandTarget(CommandTargetFlags)` are now `internal`. The remaining `public` helpers in `VisioScripting.Helpers` (`WildcardHelper`, `InteropHelper`, `SelectionHelper`) are also now `internal`. None of these appear in any documented `*Commands` method signature; they are implementation detail of the `Client` facade. The new public-API contract is captured in [`docs/decisions/visioscripting-public-api.md`](https://github.com/saveenr/VisioAutomation/blob/master/docs/decisions/visioscripting-public-api.md). Phase C of [#182](https://github.com/saveenr/VisioAutomation/issues/182).
+
 ### Fixed
 - `MsaglRenderer` now honors `Node.Size` when `Node.Cells` is also set on a directed-graph node. Previously the `Cells` assignment overwrote the entire `shape_node.Cells` object, silently dropping the `XFormWidth` / `XFormHeight` populated from `Size`, so the rendered shape came out at the master's default size instead of the requested `Size`. Now the user's `Cells` is merged onto the existing cells via `ApplyFormulasTo`, which preserves Size-derived width/height. Closes [#82](https://github.com/saveenr/VisioAutomation/issues/82).
 

VisioAutomation_2010/VTest.Models/DirectedGraphDrawModelTests.cs

@@ -300,7 +300,7 @@ public void Loader_RootElement_WrongNameThrows()
             var dg_xml = SXL.XDocument.Parse(xml);
             var client = this.GetScriptingClient();
             MUT.Assert.ThrowsExactly<System.ArgumentException>(
-                () => VisioScripting.Loaders.DirectedGraphDocumentLoader.LoadFromXml(client, dg_xml));
+                () => client.Model.LoadDirectedGraphFromXml(dg_xml));
         }
 
         [MUT.TestMethod]
@@ -364,13 +364,13 @@ private VA.Models.Layouts.DirectedGraph.DirectedGraphDocument load_two_node_grap
                 extra_attrs ?? "");
             var dg_xml = SXL.XDocument.Parse(xml);
             var client = this.GetScriptingClient();
-            return VisioScripting.Loaders.DirectedGraphDocumentLoader.LoadFromXml(client, dg_xml);
+            return client.Model.LoadDirectedGraphFromXml(dg_xml);
         }
 
         private void draw_directed_graph(VisioScripting.Client client, string dg_text)
         {
             var dg_xml = SXL.XDocument.Parse(dg_text);
-            var dgdoc = VisioScripting.Loaders.DirectedGraphDocumentLoader.LoadFromXml(client, dg_xml);
+            var dgdoc = client.Model.LoadDirectedGraphFromXml(dg_xml);
 
             // TODO: Investigate if this this special case for Visio 2013 can be removed
             // this is a temporary fix to handle the fact that server_u.vss in Visio 2013 doesn't result in server_u.vssx 

VisioAutomation_2010/VTest.Models/OrgChartDrawModelTests.cs

@@ -29,7 +29,7 @@ public void RenderOrgChart_FromSampleData_DoesNotThrow()
         private void draw_org_chart(VisioScripting.Client client, string text)
         {
             var xmldoc = SXL.XDocument.Parse(text);
-            var orgchart = VisioScripting.Loaders.OrgChartDocumentLoader.LoadFromXml(client, xmldoc);
+            var orgchart = client.Model.LoadOrgChartFromXml(xmldoc);
 
             client.Model.DrawOrgChart(VisioScripting.TargetPage.Auto, orgchart);
         }

VisioAutomation_2010/VisioPowerShell/Commands/VisioModel/ImportVisioModel.cs

@@ -1,4 +1,3 @@
-using VisioScripting.Loaders;
 using SXL = System.Xml.Linq;
 using SMA = System.Management.Automation;
 
@@ -26,13 +25,13 @@ protected override void ProcessRecord()
             if (root.Name == "directedgraph")
             {
                 this.WriteVerbose("Loading Directed Graph");
-                var dgdoc = DirectedGraphDocumentLoader.LoadFromXml(this.Client, xmldoc);
-                this.WriteObject(dgdoc);               
+                var dgdoc = this.Client.Model.LoadDirectedGraphFromXml(xmldoc);
+                this.WriteObject(dgdoc);
             }
             else if (root.Name == "orgchart")
             {
                 this.WriteVerbose("Loading as Org Chart");
-                var orgchartdoc = OrgChartDocumentLoader.LoadFromXml(this.Client, xmldoc);
+                var orgchartdoc = this.Client.Model.LoadOrgChartFromXml(xmldoc);
                 this.WriteObject(orgchartdoc);
             }
             else

VisioAutomation_2010/VisioPowerShell/Commands/VisioPage/MeasureVisioPage.cs

@@ -17,18 +17,9 @@ public class MeasureVisioPage : VisioCmdlet
 
         protected override void ProcessRecord()
         {
-
-            var targetpages = new VisioScripting.TargetPages(this.Page).ResolveToPages(this.Client);
-
-            if (targetpages.Pages.Count < 1)
-            {
-                return;
-            }
-
-            var list_pagedim = VisioScripting.Models.PageDimensions.Get_PageDimensions(targetpages.Pages);
-
+            var targetpages = new VisioScripting.TargetPages(this.Page);
+            var list_pagedim = this.Client.Page.GetPageDimensions(targetpages);
             this.WriteObject(list_pagedim,true);
-
         }
     }
 }

VisioAutomation_2010/VisioPowerShell/Commands/VisioShape/MeasureVisioShape.cs

@@ -1,4 +1,3 @@
-using System.Linq;
 using SMA = System.Management.Automation;
 using IVisio = Microsoft.Office.Interop.Visio;
 
@@ -7,29 +6,15 @@ namespace VisioPowerShell.Commands.VisioShape
     [SMA.Cmdlet(SMA.VerbsDiagnostic.Measure, Nouns.VisioShape)]
     public class MeasureVisioShape: VisioCmdlet
     {
-        // CONTEXT:SHAPES 
+        // CONTEXT:SHAPES
         [SMA.Parameter(Mandatory = false)]
         public IVisio.Shape[] Shape;
 
         protected override void ProcessRecord()
         {
-
-            var targetshapes = new VisioScripting.TargetShapes(this.Shape).ResolveToShapes(this.Client);
-
-            if (targetshapes.Shapes.Count < 1)
-            {
-                return;
-            }
-
-
-            var shapeids = VisioAutomation.Core.ShapeIDPairs.FromShapes(targetshapes.Shapes).Select(i => i.ShapeID).ToList();
-            var page = targetshapes.Shapes[0].ContainingPage;
-            var list_shapedim = VisioScripting.Models.ShapeDimensions.Get_ShapeDimensions(page, shapeids);
-
+            var targetshapes = new VisioScripting.TargetShapes(this.Shape);
+            var list_shapedim = this.Client.Selection.GetShapeDimensions(targetshapes);
             this.WriteObject(list_shapedim,true);
-
         }
-
-
     }
 }

VisioAutomation_2010/VisioScripting/Client.cs

@@ -74,7 +74,7 @@ public ClientContext ClientContext
             get { return this._client_context; }
         }
 
-        public CommandTarget GetCommandTarget(CommandTargetFlags flags)
+        internal CommandTarget GetCommandTarget(CommandTargetFlags flags)
         {
             var command_target = new CommandTarget(this, flags);
             return command_target;

VisioAutomation_2010/VisioScripting/CommandTarget.cs

@@ -3,7 +3,7 @@
 
 namespace VisioScripting
 {
-    public class CommandTarget
+    internal class CommandTarget
     {
         private readonly Client _client;
         public IVisio.Application Application { get; private set; }

VisioAutomation_2010/VisioScripting/CommandTargetFlags.cs

@@ -1,7 +1,7 @@
 namespace VisioScripting
 {
     [System.Flags]
-    public enum CommandTargetFlags
+    internal enum CommandTargetFlags
     {
         RequireApplication,
         RequireDocument,

VisioAutomation_2010/VisioScripting/Commands/ModelCommands.cs

@@ -4,6 +4,7 @@
 using ORG = VisioAutomation.Models.Documents.OrgCharts;
 using GRAPH = VisioAutomation.Models.Layouts.DirectedGraph;
 using GRID = VisioAutomation.Models.Layouts.Grid;
+using SXL = System.Xml.Linq;
 
 namespace VisioScripting.Commands
 {
@@ -192,5 +193,15 @@ public void DrawDirectedGraphDocument(GRAPH.DirectedGraphDocument dgdoc, GRAPH.D
             this._client.Output.WriteVerbose("Finished rendering all pages");
             this._client.Output.WriteVerbose("Finished rendering directed graph.");
         }
+
+        public GRAPH.DirectedGraphDocument LoadDirectedGraphFromXml(SXL.XDocument xmldoc)
+        {
+            return Loaders.DirectedGraphDocumentLoader.LoadFromXml(this._client, xmldoc);
+        }
+
+        public ORG.OrgChartDocument LoadOrgChartFromXml(SXL.XDocument xmldoc)
+        {
+            return Loaders.OrgChartDocumentLoader.LoadFromXml(this._client, xmldoc);
+        }
     }
 }

VisioAutomation_2010/VisioScripting/Commands/PageCommands.cs

@@ -60,6 +60,18 @@ public void DeletePages(TargetPages targetpages, bool renumber)
             return sizes;
         }
 
+        public List<Models.PageDimensions> GetPageDimensions(TargetPages targetpages)
+        {
+            targetpages = targetpages.ResolveToPages(this._client);
+
+            if (targetpages.Pages.Count < 1)
+            {
+                return new List<Models.PageDimensions>(0);
+            }
+
+            return Models.PageDimensions.Get_PageDimensions(targetpages.Pages);
+        }
+
         public IVisio.Page NewPage(VisioScripting.TargetDocument targetdoc, VisioAutomation.Core.Size? size, bool isbackgroundpage)
         {
             targetdoc = targetdoc.ResolveToDocument(this._client);

VisioAutomation_2010/VisioScripting/Commands/SelectionCommands.cs

@@ -267,5 +267,19 @@ public bool ContainsShapes(TargetSelection targetselection, int min_items)
             bool v = num_selected >= min_items;
             return v;
         }
+
+        public List<Models.ShapeDimensions> GetShapeDimensions(TargetShapes targetshapes)
+        {
+            targetshapes = targetshapes.ResolveToShapes(this._client);
+
+            if (targetshapes.Shapes.Count < 1)
+            {
+                return new List<Models.ShapeDimensions>(0);
+            }
+
+            var shapeids = VisioAutomation.Core.ShapeIDPairs.FromShapes(targetshapes.Shapes).Select(i => i.ShapeID).ToList();
+            var page = targetshapes.Shapes[0].ContainingPage;
+            return Models.ShapeDimensions.Get_ShapeDimensions(page, shapeids);
+        }
     }
 }

VisioAutomation_2010/VisioScripting/Helpers/InteropHelper.cs

@@ -4,7 +4,7 @@
 
 namespace VisioScripting.Helpers
 {
-    public static class InteropHelper
+    internal static class InteropHelper
     {
         private static bool _static_initialized = false;
         private static Dictionary<string, Models.EnumType> _static_g_name_to_enum;

VisioAutomation_2010/VisioScripting/Helpers/SelectionHelper.cs

@@ -5,7 +5,7 @@
 
 namespace VisioScripting.Helpers
 {
-    public static class SelectionHelper
+    internal static class SelectionHelper
     {
         public static List<IVisio.Shape> GetSelectedShapes(IVisio.Selection selection)
         {

VisioAutomation_2010/VisioScripting/Helpers/WildcardHelper.cs

@@ -3,7 +3,7 @@
 
 namespace VisioScripting.Helpers
 {
-    public static class WildcardHelper
+    internal static class WildcardHelper
     {
         public static bool NullOrStar(string s)
         {

VisioAutomation_2010/VisioScripting/Loaders/DirectedGraphDocumentLoader.cs

@@ -8,7 +8,7 @@
 
 namespace VisioScripting.Loaders
 {
-    public class DirectedGraphDocumentLoader
+    internal class DirectedGraphDocumentLoader
     {
         private class BuilderError
         {
@@ -46,12 +46,6 @@ public static BuilderError InvalidToNode(int pagenum, string conid, string toid)
             }
         }
 
-        public static DirectedGraphDocument LoadFromXml(Client client, string filename)
-        {
-            var xmldoc = SXL.XDocument.Load(filename);
-            return DirectedGraphDocumentLoader.LoadFromXml(client, xmldoc);
-        }
-
         private class PageData
         {
             public VisioAutomation.Models.ConnectorType ConnectorType;

VisioAutomation_2010/VisioScripting/Loaders/OrgChartDocumentLoader.cs

@@ -5,14 +5,8 @@
 
 namespace VisioScripting.Loaders
 {
-    public class OrgChartDocumentLoader
+    internal class OrgChartDocumentLoader
     {
-        public static VAORGCHART.OrgChartDocument LoadFromXml(Client client, string filename)
-        {
-            var xdoc = SXL.XDocument.Load(filename);
-            return OrgChartDocumentLoader.LoadFromXml(client, xdoc);
-        }
-
         public static VAORGCHART.OrgChartDocument LoadFromXml(Client client, SXL.XDocument xdoc)
         {
             var root = xdoc.Root;

VisioAutomation_2010/VisioScripting/Models/PageDimensions.cs

@@ -17,7 +17,7 @@ public class PageDimensions
         public double PrintBottomMargin;
 
 
-        public static List<PageDimensions> Get_PageDimensions(IList<IVisio.Page> pages)
+        internal static List<PageDimensions> Get_PageDimensions(IList<IVisio.Page> pages)
         {
             var list_pagedim = new List<VisioScripting.Models.PageDimensions>(pages.Count);
 

VisioAutomation_2010/VisioScripting/Models/ShapeDimensions.cs

@@ -22,7 +22,7 @@ public class ShapeDimensions
         public double OneDEndY;
 
 
-        public static List<ShapeDimensions> Get_ShapeDimensions(IVisio.Page page, List<int> shapeids)
+        internal static List<ShapeDimensions> Get_ShapeDimensions(IVisio.Page page, List<int> shapeids)
         {
             var query = new VASS.Query.CellQuery();
 

VisioAutomation_2010/VisioScripting/Properties/AssemblyInfo.cs

@@ -1,7 +1,13 @@
 using System.Reflection;
+using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
-// General Information about an assembly is controlled through the following 
+// VTest exercises a couple of VisioScripting helpers (e.g. WildcardHelper)
+// directly. The helpers are not part of the hybrid public-API contract
+// (see docs/decisions/visioscripting-public-api.md) and stay `internal`.
+[assembly: InternalsVisibleTo("VTest")]
+
+// General Information about an assembly is controlled through the following
 // set of attributes. Change these attribute values to modify the information
 // associated with an assembly.
 [assembly: AssemblyTitle("VisioScripting")]