refactor(sql): split ISqlDialect/SqlServerDialect into a .Dialect leaf (#526)
`Driver.Sql.Browser` referenced the runtime `Driver.Sql` project. The AdminUI references that browser, so the whole SQL driver runtime — and `ZB.MOM.WW.OtOpcUa.Core` through it — sat in the AdminUI's build/deploy graph. This is the same layering violation #512 removed from the MQTT browser, in a second driver, and it is why #512's expected removal of `Core.dll` from the AdminUI's output did not happen. MEASURED, both directions, on a clean AdminUI build: before: ZB.MOM.WW.OtOpcUa.Core.dll + ZB.MOM.WW.OtOpcUa.Driver.Sql.dll present after: both absent The old csproj comment's premise was sound and survives — the dialect's catalog SQL *is* the browse engine, so it must be shared rather than duplicated. What was wrong was the conclusion that sharing it required referencing the runtime driver. `ISqlDialect`/`SqlServerDialect` depend on nothing in `Driver.Sql`, so they move to a `.Dialect` leaf that both consume. This is the `.Transport` shape, not the cheap one: `ISqlDialect` exposes `DbProviderFactory` and `SqlServerDialect` returns `SqlClientFactory.Instance`, so `.Contracts` (deliberately provider-free) cannot hold them. Assembly name is `.Dialect`; the NAMESPACE stays `ZB.MOM.WW.OtOpcUa.Driver.Sql`, matching the `Driver.Mqtt.Transport` precedent — the extraction cost zero `using` changes. Two dependencies the cut edge surfaced as the implicit ones they were: - The AdminUI itself read `SqlDriver.DriverTypeName` in three places — the tag editor map, the tag config validator, and the Sql address picker. All three now read `DriverTypeNames.Sql`, which is exactly what that constant resolves to and exactly the repoint `SqlDriverBrowser`'s own comment had deferred until a factory was registered against the shared constant. One exists now. - `SqlDriverFormContractTests` asserts the AdminUI form's emitted JSON against the runtime factory that reads it, so it genuinely needs the runtime driver. `AdminUI.Tests` now references it explicitly. A test project referencing a runtime driver is fine — tests are not in the AdminUI's deploy graph. New guard: `DriverBrowserLayeringTests` (Commons.Tests) scans the csproj graph of every `*.Browser` project in the tree, transitively. It reads csproj files rather than loaded assemblies because the cost is a build-graph cost — the compiler emits no assembly reference for an unused `ProjectReference`, so `MqttBrowserLayeringTests`' assembly-reference approach cannot see that case. The two are complementary and each now points at the other. Falsified three ways, each red then green again: the direct reference re-added to the browser; the same reference one hop out via `.Dialect` (proving the walk is really transitive); and both controls — browsers-discovered and references-parsed — which exist so an empty discovery cannot pass the absence assertion vacuously. #526's claim that the reference "carries no comment at all" was wrong; it carried a detailed one from the scaffold commit. Corrected on the issue and in the design doc's project table, which had recorded the deviation as deliberate. Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,152 @@
|
||||
using System.Text.RegularExpressions;
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Commons.Tests.Browsing;
|
||||
|
||||
/// <summary>
|
||||
/// Pins the layering rule for <b>every</b> bespoke driver browser in the tree: a <c>*.Browser</c>
|
||||
/// project must not reach its runtime <c>*.Driver</c> project, by any path.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Why this exists rather than a per-driver test.</b> Gitea #512 removed this violation from
|
||||
/// the MQTT browser and pinned it with <c>MqttBrowserLayeringTests</c>. The identical violation was
|
||||
/// sitting in <c>Driver.Sql.Browser</c> the whole time and no guard saw it, because the guard was
|
||||
/// written for the driver that happened to have an issue filed (#526). This test enumerates the
|
||||
/// browsers off disk, so a browser added later is covered on the day it is added.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Why it reads csproj files rather than loaded assemblies.</b> The cost being prevented is a
|
||||
/// build/deploy-graph cost: the AdminUI references these browsers, so a runtime driver reachable
|
||||
/// from one lands in the AdminUI's output whether or not a single type is used. The compiler emits
|
||||
/// no assembly reference for an unused <c>ProjectReference</c>, so an assembly-reference test —
|
||||
/// which is what <c>MqttBrowserLayeringTests</c> does, and says so — cannot see that case. The two
|
||||
/// are complementary: this one catches the reference, that one catches the usage.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The walk is transitive.</b> Asserting only on direct references would pass a browser that
|
||||
/// reached its runtime driver through a shared leaf, which is the same defect one hop further out
|
||||
/// — the hazard <c>MqttBrowserLayeringTests</c> guards for <c>.Transport</c> by hand.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class DriverBrowserLayeringTests
|
||||
{
|
||||
/// <summary>
|
||||
/// Browsers known to exist when this guard was written. Asserted as a MINIMUM, not an exact set —
|
||||
/// a new browser must be covered automatically, so this list only defends against the discovery
|
||||
/// itself silently finding nothing (a wrong repo root, a moved directory), which would make every
|
||||
/// assertion below vacuously true.
|
||||
/// </summary>
|
||||
private static readonly string[] KnownBrowsers =
|
||||
[
|
||||
"ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser",
|
||||
"ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser",
|
||||
"ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser",
|
||||
"ZB.MOM.WW.OtOpcUa.Driver.Sql.Browser",
|
||||
];
|
||||
|
||||
[Fact]
|
||||
public void Every_bespoke_browser_is_discovered()
|
||||
{
|
||||
// The positive control for the whole file. Every other test here is an ABSENCE assertion over a
|
||||
// discovered set, so an empty set passes them all.
|
||||
var discovered = DiscoverBrowsers().Select(p => Path.GetFileNameWithoutExtension(p)!).ToArray();
|
||||
|
||||
foreach (var known in KnownBrowsers)
|
||||
discovered.ShouldContain(known);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Every_browser_declares_at_least_one_project_reference()
|
||||
// The second half of the control: proves the csproj parse actually returns something, so a
|
||||
// regex that silently stopped matching cannot turn the rule below into a no-op.
|
||||
=> DiscoverBrowsers().ShouldAllBe(p => DirectReferences(p).Count > 0);
|
||||
|
||||
[Fact]
|
||||
public void No_browser_reaches_its_runtime_driver_project()
|
||||
{
|
||||
var offenders = new List<string>();
|
||||
|
||||
foreach (var browser in DiscoverBrowsers())
|
||||
{
|
||||
var browserName = Path.GetFileNameWithoutExtension(browser)!;
|
||||
|
||||
// "ZB…Driver.Sql.Browser" -> "ZB…Driver.Sql": the sibling runtime project.
|
||||
var runtime = browserName[..^".Browser".Length];
|
||||
|
||||
var reached = TransitiveReferences(browser);
|
||||
if (reached.Contains(runtime))
|
||||
offenders.Add($"{browserName} -> {runtime}");
|
||||
}
|
||||
|
||||
offenders.ShouldBeEmpty(
|
||||
"a driver browser reaches its runtime driver project. The AdminUI references these browsers, "
|
||||
+ "so the whole driver runtime lands in its build/deploy graph — the cost is invisible, which "
|
||||
+ "is exactly why it needs a guard. If shared code is needed, put transport-free protocol or "
|
||||
+ "contract types in .Contracts, and anything that must name a provider/vendor type in a leaf "
|
||||
+ "project of its own (see Driver.Mqtt.Transport and Driver.Sql.Dialect). Do NOT resolve this "
|
||||
+ "by copying the shared code into the browser: for anything touching credentials, TLS or "
|
||||
+ "identifier quoting, a second copy is a silent security divergence rather than a build break.");
|
||||
}
|
||||
|
||||
// ---- csproj graph ------------------------------------------------------------------------------
|
||||
|
||||
private static readonly Regex ProjectReferencePattern = new(
|
||||
"<ProjectReference\\s+Include\\s*=\\s*\"([^\"]+)\"",
|
||||
RegexOptions.IgnoreCase | RegexOptions.Compiled);
|
||||
|
||||
private static IReadOnlyList<string> DiscoverBrowsers() =>
|
||||
[.. Directory
|
||||
.EnumerateDirectories(Path.Combine(RepoRoot.Value, "src", "Drivers"), "*.Browser")
|
||||
.Select(d => Path.Combine(d, Path.GetFileName(d) + ".csproj"))
|
||||
.Where(File.Exists)
|
||||
.OrderBy(p => p, StringComparer.Ordinal)];
|
||||
|
||||
/// <summary>Absolute paths of the csproj files one project references directly.</summary>
|
||||
private static IReadOnlyList<string> DirectReferences(string csprojPath)
|
||||
{
|
||||
var dir = Path.GetDirectoryName(csprojPath)!;
|
||||
|
||||
return
|
||||
[
|
||||
.. ProjectReferencePattern
|
||||
.Matches(File.ReadAllText(csprojPath))
|
||||
.Select(m => Path.GetFullPath(
|
||||
Path.Combine(dir, m.Groups[1].Value.Replace('\\', Path.DirectorySeparatorChar))))
|
||||
];
|
||||
}
|
||||
|
||||
/// <summary>Assembly-ish names of every project reachable from <paramref name="csprojPath"/>.</summary>
|
||||
private static HashSet<string> TransitiveReferences(string csprojPath)
|
||||
{
|
||||
var reached = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
|
||||
var pending = new Stack<string>(DirectReferences(csprojPath));
|
||||
|
||||
while (pending.Count > 0)
|
||||
{
|
||||
var next = pending.Pop();
|
||||
if (!reached.Add(Path.GetFileNameWithoutExtension(next)!) || !File.Exists(next)) continue;
|
||||
|
||||
foreach (var onward in DirectReferences(next)) pending.Push(onward);
|
||||
}
|
||||
|
||||
return reached;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Walks up from the test binary until the solution file appears. The tests run out of
|
||||
/// <c>bin/Debug/net10.0</c>, so no fixed relative depth is reliable across host layouts.
|
||||
/// </summary>
|
||||
private static readonly Lazy<string> RepoRoot = new(() =>
|
||||
{
|
||||
var dir = new DirectoryInfo(AppContext.BaseDirectory);
|
||||
|
||||
while (dir is not null && !File.Exists(Path.Combine(dir.FullName, "ZB.MOM.WW.OtOpcUa.slnx")))
|
||||
dir = dir.Parent;
|
||||
|
||||
dir.ShouldNotBeNull("could not locate the repository root (no ZB.MOM.WW.OtOpcUa.slnx above the test binary)");
|
||||
return dir.FullName;
|
||||
});
|
||||
}
|
||||
@@ -22,6 +22,14 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests;
|
||||
/// <c>ProjectReference</c> re-added but never used would not trip it (the compiler emits no
|
||||
/// reference), so the csproj comment remains the primary record of the decision.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>That gap is now covered</b> by <c>DriverBrowserLayeringTests</c> (Commons.Tests), which
|
||||
/// scans the csproj graph of every <c>*.Browser</c> project in the tree — added for Gitea #526,
|
||||
/// after the identical violation was found sitting in <c>Driver.Sql.Browser</c> with no guard
|
||||
/// watching it, because this file was written for the one driver that had an issue filed. What
|
||||
/// stays here is the MQTT-specific half: the <c>.Transport</c> leaf shape and the
|
||||
/// MQTTnet-free-ness of <c>.Contracts</c>.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class MqttBrowserLayeringTests
|
||||
|
||||
@@ -25,6 +25,13 @@
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\..\src\Server\ZB.MOM.WW.OtOpcUa.AdminUI\ZB.MOM.WW.OtOpcUa.AdminUI.csproj"/>
|
||||
<ProjectReference Include="..\..\..\src\Core\ZB.MOM.WW.OtOpcUa.Core\ZB.MOM.WW.OtOpcUa.Core.csproj"/>
|
||||
<!-- SqlDriverFormContractTests asserts the AdminUI form's emitted JSON against the runtime
|
||||
factory that reads it, so it genuinely needs the runtime driver. It used to arrive here
|
||||
transitively through AdminUI -> Driver.Sql.Browser -> Driver.Sql; Gitea #526 cut that
|
||||
edge, which is what surfaced this dependency as the implicit one it always was. A TEST
|
||||
project referencing a runtime driver is fine — tests are not in the AdminUI's deploy
|
||||
graph, which is the whole thing #526 was about. -->
|
||||
<ProjectReference Include="..\..\..\src\Drivers\ZB.MOM.WW.OtOpcUa.Driver.Sql\ZB.MOM.WW.OtOpcUa.Driver.Sql.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
|
||||
Reference in New Issue
Block a user