@phuc1403/musketeer 0.9.0 → 0.11.0

package/template/.claude/skills/logical-components/scripts/LogicalComponents/ComponentDiscovery.cs

@@ -0,0 +1,166 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Lists the candidates (every type in an Application or Infrastructure project that passes <see cref="ComponentRule"/>)
+/// and keeps as components the ones the repo's frozen classification calls components. Output order is by full type
+/// name, so the same code and config always yield the same list.
+/// </summary>
+public static class ComponentDiscovery
+{
+    public const string ApplicationLayer = "Application";
+    public const string InfrastructureLayer = "Infrastructure";
+
+    /// <summary>The candidates, as components not yet named (empty id and name), plus out-of-repo warnings.</summary>
+    public sealed record CandidateList(IReadOnlyList<Component> Candidates, IReadOnlyList<string> Warnings);
+
+    public static async Task<CandidateList> CandidatesAsync(LoadedWorkspace loaded, CancellationToken cancellationToken = default)
+    {
+        var warnings = new List<string>();
+        var candidates = (await SourceTypesAsync(loaded.Solution, cancellationToken))
+            .Where(t => t.Layer is (ApplicationLayer or InfrastructureLayer) && ComponentRule.IsCandidate(t.Symbol))
+            .Select(t => ToComponent(t, loaded, warnings))
+            .OfType<Component>()
+            .ToList();
+        return new CandidateList(candidates, warnings);
+    }
+
+    public static async Task<DiscoveryResult> DiscoverAsync(
+        LoadedWorkspace loaded, ExtractConfig config, CancellationToken cancellationToken = default)
+    {
+        var (candidates, candidateWarnings) = await CandidatesAsync(loaded, cancellationToken);
+        var known = candidates.Select(c => c.Type).ToHashSet(StringComparer.Ordinal);
+        var stale = config.Components.Concat(config.Helpers.Keys)
+            .Where(name => !known.Contains(name))
+            .Distinct()
+            .Order(StringComparer.Ordinal)
+            .Select(name => $"config entry '{name}' names no candidate; ignored");
+
+        return new DiscoveryResult(
+            AssignIds(candidates.Where(c => config.Components.Contains(c.Type)).ToList()),
+            candidates.Where(c => !config.IsClassified(c.Type)).Select(c => c.Type).ToList(),
+            [.. candidateWarnings, .. stale]);
+    }
+
+    /// <summary>A top-level type declared in a loaded project, with the layer and module its project gives it.</summary>
+    public sealed record SourceType(INamedTypeSymbol Symbol, string Layer, string Module);
+
+    public static async Task<List<SourceType>> SourceTypesAsync(Solution solution, CancellationToken cancellationToken)
+    {
+        var types = new List<SourceType>();
+        foreach (var project in solution.Projects)
+        {
+            var compilation = await project.GetCompilationAsync(cancellationToken)
+                ?? throw new InvalidOperationException($"No compilation for {project.Name}");
+            var (layer, module) = LayerAndModule(project.Name);
+            types.AddRange(TopLevelTypes(compilation.Assembly.GlobalNamespace)
+                .Where(t => t.Locations.Any(l => l.IsInSource))
+                .Select(t => new SourceType(t, layer, module)));
+        }
+
+        return types.OrderBy(t => SymbolNames.FullName(t.Symbol), StringComparer.Ordinal).ToList();
+    }
+
+    /// <summary>
+    /// <c>WorkerDwg.Export.Application</c> → (Application, Export); <c>Sample.Infrastructure</c> → (Infrastructure, Sample);
+    /// any other project → (Other, its last name segment).
+    /// </summary>
+    public static (string Layer, string Module) LayerAndModule(string projectName)
+    {
+        foreach (var layer in new[] { ApplicationLayer, InfrastructureLayer })
+        {
+            if (projectName.EndsWith("." + layer, StringComparison.Ordinal))
+            {
+                var rest = projectName[..^(layer.Length + 1)];
+                return (layer, rest[(rest.LastIndexOf('.') + 1)..]);
+            }
+        }
+
+        return ("Other", projectName[(projectName.LastIndexOf('.') + 1)..]);
+    }
+
+    /// <summary>
+    /// Ids and names are the plain type name unless several components share it; then every one of them is prefixed
+    /// with its module (<c>Export_JobOutcomeReporting</c>, "Job Outcome Reporting (Export)"). If that still clashes
+    /// (same module, different namespace or generic arity), the full type name disambiguates. The same full type twice
+    /// (a file linked into two projects) has no honest id and is an error.
+    /// </summary>
+    public static List<Component> AssignIds(IReadOnlyList<Component> components)
+    {
+        var duplicateTypes = components.GroupBy(c => c.Type).Where(g => g.Count() > 1).Select(g => g.Key).ToList();
+        if (duplicateTypes.Count > 0)
+        {
+            throw new InvalidOperationException(
+                $"Declared in more than one project, so no unique component id: {string.Join(", ", duplicateTypes.Order(StringComparer.Ordinal))}");
+        }
+
+        var bySimpleName = components.GroupBy(c => SymbolNames.SimpleName(c.Type)).ToDictionary(g => g.Key, g => g.Count());
+        var named = components.Select(c =>
+        {
+            var simple = SymbolNames.SimpleName(c.Type);
+            var words = DisplayName.FromTypeName(simple);
+            return bySimpleName[simple] == 1
+                ? c with { Id = simple, Name = words }
+                : c with { Id = $"{c.Module}_{simple}", Name = $"{words} ({c.Module})" };
+        }).ToList();
+
+        var clashingIds = named.GroupBy(c => c.Id).Where(g => g.Count() > 1).Select(g => g.Key).ToHashSet();
+        return named
+            .Select(c => clashingIds.Contains(c.Id)
+                ? c with
+                {
+                    Id = SymbolNames.ToIdentifier(c.Type),
+                    Name = $"{DisplayName.FromTypeName(SymbolNames.SimpleName(c.Type))} ({SymbolNames.ReadableFullName(c.Type)})",
+                }
+                : c)
+            .OrderBy(c => c.Type, StringComparer.Ordinal)
+            .ToList();
+    }
+
+    /// <summary>
+    /// The component for a type, with spans from real source files inside the repo only. Generator output (under obj/)
+    /// is skipped silently; a declaration outside the repo cannot be cited, so it is skipped with a warning. No span
+    /// left means no component.
+    /// </summary>
+    public static Component? ToComponent(SourceType type, LoadedWorkspace loaded, List<string> warnings)
+    {
+        var spans = new List<SourceSpan>();
+        foreach (var reference in type.Symbol.DeclaringSyntaxReferences)
+        {
+            var (kind, relative) = CitableSource.Classify(loaded, reference.SyntaxTree);
+            if (kind == CitableSource.Kind.OutsideRepo)
+            {
+                var warning = $"declaration of {SymbolNames.FullName(type.Symbol)} outside the repo was ignored";
+                if (!warnings.Contains(warning))
+                {
+                    warnings.Add(warning);
+                }
+            }
+
+            if (kind != CitableSource.Kind.InRepo)
+            {
+                continue;
+            }
+
+            var lines = reference.GetSyntax().GetLocation().GetLineSpan();
+            spans.Add(new SourceSpan(relative, lines.StartLinePosition.Line + 1, lines.EndLinePosition.Line + 1));
+        }
+
+        if (spans.Count == 0)
+        {
+            return null;
+        }
+
+        return new Component(
+            Id: "",
+            Type: SymbolNames.FullName(type.Symbol),
+            Name: "",
+            Module: type.Module,
+            Layer: type.Layer,
+            Spans: spans.OrderBy(s => s.File, StringComparer.Ordinal).ThenBy(s => s.Start).ToList());
+    }
+
+    private static IEnumerable<INamedTypeSymbol> TopLevelTypes(INamespaceSymbol ns) =>
+        ns.GetTypeMembers().Concat(ns.GetNamespaceMembers().SelectMany(TopLevelTypes));
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/ComponentRule.cs

@@ -0,0 +1,87 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// The deterministic test for "could this type be a logical component". Whether a candidate IS one is not decided here:
+/// the repo's frozen classification (<see cref="ExtractConfig"/>) says component or helper. Whether a declaration comes
+/// from a real file inside the repo is checked by discovery, which has the solution to hand.
+/// </summary>
+public static class ComponentRule
+{
+    private const string ServiceCollection = "Microsoft.Extensions.DependencyInjection.IServiceCollection";
+
+    /// <summary>
+    /// A candidate is a top-level, source-declared class (static classes included) or record (abstract records and
+    /// record structs included) that is not an abstract class (a seam), not file-local, not an exception, not an
+    /// <c>*Options</c> class, not a DI composition root, and declares at least one method with a body of its own.
+    /// </summary>
+    public static bool IsCandidate(INamedTypeSymbol type) =>
+        (type.TypeKind == TypeKind.Class || (type.TypeKind == TypeKind.Struct && type.IsRecord))
+        && !EdgeExtraction.IsSeam(type)
+        && !type.IsImplicitlyDeclared
+        // A file-local type's metadata name embeds a hash of its absolute path: different per checkout.
+        && !type.IsFileLocal
+        && type.ContainingType is null
+        && type.Locations.Any(l => l.IsInSource)
+        && !type.Name.EndsWith("Options", StringComparison.Ordinal)
+        && !IsException(type)
+        && !IsCompositionRoot(type)
+        && DeclaresBehaviour(type);
+
+    /// <summary>
+    /// A static class that extends <c>IServiceCollection</c> (classic <c>this</c> parameter or a C# 14
+    /// <c>extension(IServiceCollection)</c> block) wires the app together and <c>new</c>s nearly every class; counting it
+    /// would make it look coupled to everything.
+    /// </summary>
+    public static bool IsCompositionRoot(INamedTypeSymbol type) =>
+        type.IsStatic
+        && (type.GetMembers().OfType<IMethodSymbol>().Any(m =>
+                m.IsExtensionMethod && m.Parameters.Length > 0 && IsServiceCollection(m.Parameters[0].Type))
+            || ExtensionBlocks(type).Any(block =>
+                block.ExtensionParameter is { } parameter && IsServiceCollection(parameter.Type)));
+
+    // An exception carries a failure; even with factory methods of its own it is data, not a unit of behaviour.
+    private static bool IsException(INamedTypeSymbol type)
+    {
+        for (var current = type.BaseType; current is not null; current = current.BaseType)
+        {
+            if (SymbolNames.QualifiedName(current) == "System.Exception")
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// An ordinary method, explicit interface implementation, or C# 14 extension member written in the type, with a body.
+    /// Not behaviour: constructors, accessors, operators, abstract methods, compiler-synthesized record members, and
+    /// overrides of <c>object.ToString/Equals/GetHashCode</c> (formatting or comparing what the type holds).
+    /// </summary>
+    private static bool DeclaresBehaviour(INamedTypeSymbol type) =>
+        type.GetMembers().Concat(ExtensionBlocks(type).SelectMany(block => block.GetMembers()))
+            .OfType<IMethodSymbol>()
+            .Any(m => !m.IsImplicitlyDeclared
+                && !m.IsAbstract
+                && !(m.IsPartialDefinition && m.PartialImplementationPart is null)
+                && m.MethodKind is MethodKind.Ordinary or MethodKind.ExplicitInterfaceImplementation
+                && !OverridesObjectMember(m));
+
+    private static bool OverridesObjectMember(IMethodSymbol method)
+    {
+        var overridden = method.OverriddenMethod;
+        while (overridden?.OverriddenMethod is { } further)
+        {
+            overridden = further;
+        }
+
+        return overridden?.ContainingType.SpecialType == SpecialType.System_Object;
+    }
+
+    private static IEnumerable<INamedTypeSymbol> ExtensionBlocks(INamedTypeSymbol type) =>
+        type.GetTypeMembers().Where(t => t.IsExtension);
+
+    private static bool IsServiceCollection(ITypeSymbol type) => SymbolNames.QualifiedName(type) == ServiceCollection;
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/ComponentsFile.cs

@@ -0,0 +1,83 @@
+using System.Text;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+
+namespace LogicalComponents;
+
+/// <summary>Where a component's declaration lives: repo-relative path with forward slashes, 1-based inclusive lines.</summary>
+public sealed record SourceSpan(string File, int Start, int End);
+
+/// <summary>
+/// One logical component: a class the repo config classifies as a unit of behaviour.
+/// <see cref="Id"/> is what the diagram uses; <see cref="Type"/> is the full metadata name. <see cref="Reaches"/> is
+/// the helper code (members of helpers, records and other non-components) that the component's code runs: a rule held
+/// there is part of what the component does, so its responsibilities may cite it. Null until coupling is resolved.
+/// </summary>
+public sealed record Component(
+    string Id,
+    string Type,
+    string Name,
+    string Module,
+    string Layer,
+    IReadOnlyList<SourceSpan> Spans,
+    IReadOnlyList<SourceSpan>? Reaches = null);
+
+/// <summary>
+/// The classified components, the candidates the config does not classify yet (extract refuses to run with any), and
+/// warnings.
+/// </summary>
+public sealed record DiscoveryResult(
+    IReadOnlyList<Component> Components, IReadOnlyList<string> Unclassified, IReadOnlyList<string> Warnings);
+
+/// <summary>A diagram node that is not a component: an interface (<c>layer: "port"</c>) with no modelled implementation.</summary>
+public sealed record ExternalNode(string Id, string Type, string Name, string Layer);
+
+/// <summary>
+/// One coupling edge between two node ids. <see cref="Kinds"/> is the sorted set of di/new/static, <see cref="Via"/> the
+/// sorted interfaces it went through, <see cref="At"/> its first occurrence as <c>file:line</c>.
+/// </summary>
+public sealed record Edge(string From, string To, IReadOnlyList<string> Kinds, IReadOnlyList<string> Via, string At);
+
+/// <summary>Everything <c>extract</c> writes: the components, the ports they reach, the edges, and the warnings.</summary>
+public sealed record ExtractResult(
+    IReadOnlyList<Component> Components,
+    IReadOnlyList<ExternalNode> ExternalNodes,
+    IReadOnlyList<Edge> Edges,
+    IReadOnlyList<string> Warnings);
+
+/// <summary>
+/// Writes <c>components.json</c>. Byte-identical for identical input: fixed property order, LF line endings,
+/// no BOM, no timestamps, and only repo-relative paths.
+/// </summary>
+public static class ComponentsFile
+{
+    private static readonly JsonSerializerOptions Options = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        WriteIndented = true,
+        IndentSize = 2,
+        NewLine = "\n",
+        // Keep names and paths readable; the file is consumed by our own tools and by agents, not by browsers.
+        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
+    };
+
+    public static byte[] Serialize(ExtractResult result) =>
+        ToJson(new
+        {
+            components = result.Components,
+            externalNodes = result.ExternalNodes,
+            edges = result.Edges,
+            warnings = result.Warnings,
+        });
+
+    /// <summary>Any file the tool writes: indented camelCase JSON, LF line endings, no BOM, trailing newline.</summary>
+    public static byte[] ToJson<T>(T value) =>
+        new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(JsonSerializer.Serialize(value, Options) + "\n");
+
+    /// <summary>Reads a components.json written by <see cref="Serialize(ExtractResult)"/>.</summary>
+    public static ExtractResult Deserialize(byte[] json) => FromJson<ExtractResult>(json);
+
+    /// <summary>Reads any file written by <see cref="ToJson{T}"/>.</summary>
+    public static T FromJson<T>(byte[] json) =>
+        JsonSerializer.Deserialize<T>(json, Options) ?? throw new JsonException("the file is empty");
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/CouplingResolver.cs

@@ -0,0 +1,196 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// The whole <c>extract</c> computation: the classified components, and an edge A → B for every way A depends on B:
+/// A takes B (or a seam B implements) in its constructor (<c>di</c>), derives from B (<c>inherits</c>), or its code
+/// runs B's code, directly or through seams and helpers (<c>new</c>, <c>static</c>, <c>call</c>; see
+/// <see cref="MemberUseResolution"/>). Output order is fixed, so the same code and config yield the same bytes.
+/// </summary>
+public static class CouplingResolver
+{
+    public static async Task<ExtractResult> ExtractAsync(
+        LoadedWorkspace loaded, ExtractConfig config, CancellationToken cancellationToken = default)
+    {
+        var discovery = await ComponentDiscovery.DiscoverAsync(loaded, config, cancellationToken);
+        if (discovery.Unclassified.Count > 0)
+        {
+            throw new UnclassifiedCandidatesException(discovery.Unclassified);
+        }
+
+        var sourceTypes = (await ComponentDiscovery.SourceTypesAsync(loaded.Solution, cancellationToken))
+            .Where(t => t.Layer is ComponentDiscovery.ApplicationLayer or ComponentDiscovery.InfrastructureLayer)
+            .GroupBy(t => SymbolNames.FullName(t.Symbol))
+            .ToDictionary(g => g.Key, g => g.First().Symbol, StringComparer.Ordinal);
+        var components = discovery.Components.Select(c => c.Type).ToHashSet(StringComparer.Ordinal);
+        var warnings = await CompileErrorWarningsAsync(loaded.Solution, cancellationToken);
+        var ports = new SortedDictionary<string, INamedTypeSymbol>(StringComparer.Ordinal);
+        var raw = new List<MemberUseResolution.RawEdge>();
+        var portResolution = new PortResolution(loaded.Solution);
+        var resolution = new MemberUseResolution(loaded, components, portResolution);
+        var reaches = new Dictionary<string, List<SourceSpan>>(StringComparer.Ordinal);
+
+        foreach (var component in discovery.Components)
+        {
+            var symbol = sourceTypes[component.Type];
+            var self = new HashSet<string>(StringComparer.Ordinal) { component.Type };
+            var declarations = symbol.DeclaringSyntaxReferences.Select(r => r.GetSyntax()).ToList();
+            var roots = new List<SyntaxNode>(declarations);
+
+            // Up the base chain: the first component ancestor is an 'inherits' edge; the code of non-component source
+            // bases in between (typically abstract) is this component's own behaviour, so it is walked as such.
+            for (var baseType = symbol.BaseType?.OriginalDefinition;
+                 baseType is not null && CitableSource.IsRepoSource(baseType, loaded);
+                 baseType = baseType.BaseType?.OriginalDefinition)
+            {
+                var baseName = SymbolNames.FullName(baseType);
+                if (components.Contains(baseName))
+                {
+                    var (file, line) = BaseListLocation(declarations, loaded) ?? (component.Spans[0].File, component.Spans[0].Start);
+                    raw.Add(new(component.Type, baseName, EdgeExtraction.Inherits, [], file, line));
+                    break;
+                }
+
+                self.Add(baseName);
+                roots.AddRange(baseType.DeclaringSyntaxReferences.Select(r => r.GetSyntax()));
+            }
+
+            foreach (var reference in EdgeExtraction.DiReferences(symbol, loaded))
+            {
+                raw.AddRange(await DiEdgesAsync(component.Type, reference, components, ports, portResolution, loaded, cancellationToken));
+            }
+
+            // In (file, position) order, so the first path the walk records is the same on every checkout.
+            var ordered = roots.OrderBy(r => r.SyntaxTree.FilePath, StringComparer.Ordinal).ThenBy(r => r.SpanStart);
+            var uses = await MemberUses.ReadAsync(ordered, loaded, cancellationToken);
+            var resolved = await resolution.ResolveAsync(component.Type, self, uses, cancellationToken);
+            raw.AddRange(resolved.Edges);
+            reaches[component.Type] = resolved.Reaches;
+        }
+
+        var ids = discovery.Components.ToDictionary(c => c.Type, c => c.Id, StringComparer.Ordinal);
+        var externalNodes = PortNodes(ports, ids);
+        foreach (var node in externalNodes)
+        {
+            ids[node.Type] = node.Id;
+        }
+
+        warnings.AddRange(ports.Keys.Select(p => $"port {p} has no implementation"));
+        return new ExtractResult(
+            discovery.Components.Select(c => c with { Reaches = reaches[c.Type] }).ToList(),
+            externalNodes,
+            MergeEdges(raw, ids),
+            [.. discovery.Warnings, .. warnings.Where(w => !discovery.Warnings.Contains(w)).Distinct().Order(StringComparer.Ordinal)]);
+    }
+
+    /// <summary>
+    /// A constructor parameter as edges: to the component it is, to every component implementing the seam it is, or to
+    /// a port node when nothing in the repo implements that seam. A parameter of a helper type is no edge; what the
+    /// component calls on it is found by <see cref="MemberUseResolution"/>.
+    /// </summary>
+    private static async Task<List<MemberUseResolution.RawEdge>> DiEdgesAsync(
+        string from,
+        EdgeExtraction.Reference reference,
+        IReadOnlySet<string> components,
+        SortedDictionary<string, INamedTypeSymbol> ports,
+        PortResolution portResolution,
+        LoadedWorkspace loaded,
+        CancellationToken cancellationToken)
+    {
+        var target = reference.Target;
+        if (!EdgeExtraction.IsSeam(target))
+        {
+            var name = SymbolNames.FullName(target);
+            return components.Contains(name) ? [new(from, name, EdgeExtraction.Di, [], reference.File, reference.Line)] : [];
+        }
+
+        // Seams from the framework (ILogger<T>, IReadOnlyList<T>...) are plumbing, not design.
+        if (!CitableSource.IsRepoSource(target.OriginalDefinition, loaded))
+        {
+            return [];
+        }
+
+        var implementations = await portResolution.ImplementationsAsync(target, cancellationToken);
+        if (implementations.Count == 0)
+        {
+            var portName = SymbolNames.FullName(target.OriginalDefinition);
+            ports[portName] = target.OriginalDefinition;
+            return [new(from, portName, EdgeExtraction.Di, [], reference.File, reference.Line)];
+        }
+
+        return implementations
+            .Select(SymbolNames.FullName)
+            .Where(components.Contains)
+            .Select(to => new MemberUseResolution.RawEdge(from, to, EdgeExtraction.Di, [target.Name], reference.File, reference.Line))
+            .ToList();
+    }
+
+    /// <summary>Where a partial class names its base class: the base list of the declaration that has one.</summary>
+    private static (string File, int Line)? BaseListLocation(IEnumerable<SyntaxNode> declarations, LoadedWorkspace loaded)
+    {
+        foreach (var baseList in declarations.OfType<Microsoft.CodeAnalysis.CSharp.Syntax.TypeDeclarationSyntax>()
+                     .Select(d => d.BaseList).OfType<Microsoft.CodeAnalysis.CSharp.Syntax.BaseListSyntax>())
+        {
+            var (kind, file) = CitableSource.Classify(loaded, baseList.SyntaxTree);
+            if (kind == CitableSource.Kind.InRepo)
+            {
+                return (file, baseList.GetLocation().GetLineSpan().StartLinePosition.Line + 1);
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>Code that does not compile binds partially, so edges can be missing: say so instead of staying silent.</summary>
+    private static async Task<List<string>> CompileErrorWarningsAsync(Solution solution, CancellationToken cancellationToken)
+    {
+        var warnings = new List<string>();
+        foreach (var project in solution.Projects.OrderBy(p => p.Name, StringComparer.Ordinal))
+        {
+            var compilation = await project.GetCompilationAsync(cancellationToken);
+            var errors = compilation?.GetDiagnostics(cancellationToken).Count(d => d.Severity == DiagnosticSeverity.Error) ?? 0;
+            if (errors > 0)
+            {
+                warnings.Add($"project {project.Name} has {errors} compile error(s); coupling may be incomplete");
+            }
+        }
+
+        return warnings;
+    }
+
+    /// <summary>Port nodes use the seam's simple name as id, unless that clashes with a component or another port.</summary>
+    private static List<ExternalNode> PortNodes(
+        SortedDictionary<string, INamedTypeSymbol> ports, IReadOnlyDictionary<string, string> componentIds)
+    {
+        var taken = componentIds.Values.ToHashSet(StringComparer.Ordinal);
+        var bySimpleName = ports.Values.GroupBy(p => p.Name).ToDictionary(g => g.Key, g => g.Count());
+        return ports
+            .Select(p =>
+            {
+                var simple = p.Value.Name;
+                var id = bySimpleName[simple] == 1 && !taken.Contains(simple) ? simple : SymbolNames.ToIdentifier(p.Key);
+                return new ExternalNode(id, p.Key, DisplayName.FromTypeName(simple), "port");
+            })
+            .OrderBy(n => n.Id, StringComparer.Ordinal)
+            .ToList();
+    }
+
+    /// <summary>One edge per (from, to): kinds and via as sorted sets, cited at the earliest (file, line) recorded use.</summary>
+    private static List<Edge> MergeEdges(List<MemberUseResolution.RawEdge> raw, IReadOnlyDictionary<string, string> ids) =>
+        raw.Where(e => e.From != e.To)
+            .GroupBy(e => (From: ids[e.From], To: ids[e.To]))
+            .Select(g =>
+            {
+                var first = g.OrderBy(e => e.File, StringComparer.Ordinal).ThenBy(e => e.Line).First();
+                return new Edge(
+                    g.Key.From,
+                    g.Key.To,
+                    g.Select(e => e.Kind).Distinct().Order(StringComparer.Ordinal).ToList(),
+                    g.SelectMany(e => e.Via).Distinct().Order(StringComparer.Ordinal).ToList(),
+                    $"{first.File}:{first.Line}");
+            })
+            .OrderBy(e => e.From, StringComparer.Ordinal)
+            .ThenBy(e => e.To, StringComparer.Ordinal)
+            .ToList();
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/DisplayName.cs

@@ -0,0 +1,14 @@
+using System.Text.RegularExpressions;
+
+namespace LogicalComponents;
+
+/// <summary>Turns a PascalCase type name into the words shown in the doc: ExportJobAcceptance → Export Job Acceptance.</summary>
+public static partial class DisplayName
+{
+    public static string FromTypeName(string typeName) => WordBoundary().Replace(typeName, " ");
+
+    // A boundary sits before an uppercase letter that follows a lowercase letter or digit (JobAcceptance, Utf8Decoding),
+    // or before the last capital of an acronym run that starts a new word (IOStream → IO Stream).
+    [GeneratedRegex("(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")]
+    private static partial Regex WordBoundary();
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/EdgeExtraction.cs

@@ -0,0 +1,111 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// The edge kinds, and what a component's constructors take (<c>di</c>: each parameter's type, primary constructors
+/// included, looked through wrappers). The uses inside code are read by <see cref="MemberUses"/>.
+/// </summary>
+public static class EdgeExtraction
+{
+    public const string Call = "call";
+    public const string Di = "di";
+    public const string Inherits = "inherits";
+    public const string New = "new";
+    public const string Static = "static";
+
+    /// <summary>A constructor parameter's type, at a repo-relative file and 1-based line.</summary>
+    public sealed record Reference(INamedTypeSymbol Target, string Kind, string File, int Line);
+
+    /// <summary>What the type's constructors take: each parameter's type, looked through wrappers.</summary>
+    public static List<Reference> DiReferences(INamedTypeSymbol type, LoadedWorkspace loaded)
+    {
+        var references = new List<Reference>();
+        foreach (var constructor in type.InstanceConstructors.Where(c => !c.IsImplicitlyDeclared))
+        {
+            foreach (var parameter in constructor.Parameters)
+            {
+                var location = parameter.Locations.FirstOrDefault(l => l.IsInSource);
+                var (kind, file) = CitableSource.Classify(loaded, location?.SourceTree);
+                if (kind == CitableSource.Kind.InRepo)
+                {
+                    var line = location!.GetLineSpan().StartLinePosition.Line + 1;
+                    references.AddRange(DiTargets(parameter.Type).Select(t => new Reference(t, Di, file, line)));
+                }
+            }
+        }
+
+        return references;
+    }
+
+    // Containers that deliver a dependency without being one: the dependency is what they wrap.
+    private static readonly HashSet<string> Wrappers =
+    [
+        "System.Collections.Generic.IEnumerable`1",
+        "System.Collections.Generic.IReadOnlyCollection`1",
+        "System.Collections.Generic.IReadOnlyList`1",
+        "System.Collections.Generic.ICollection`1",
+        "System.Collections.Generic.IList`1",
+        "System.Lazy`1",
+        "System.Func`1",
+    ];
+
+    /// <summary>
+    /// What a constructor parameter depends on: the type itself, or what a wrapper delivers (<c>IEnumerable&lt;IX&gt;</c>,
+    /// <c>IReadOnlyList&lt;IX&gt;</c>, <c>Lazy&lt;X&gt;</c>, <c>Func&lt;X&gt;</c>, <c>X[]</c>), looked through recursively.
+    /// </summary>
+    private static IEnumerable<INamedTypeSymbol> DiTargets(ITypeSymbol type)
+    {
+        switch (type)
+        {
+            case IArrayTypeSymbol array:
+                foreach (var element in DiTargets(array.ElementType))
+                {
+                    yield return element;
+                }
+
+                break;
+            case INamedTypeSymbol { IsGenericType: true } named
+                when Wrappers.Contains(SymbolNames.FullName(named.OriginalDefinition)):
+                foreach (var element in DiTargets(named.TypeArguments[0]))
+                {
+                    yield return element;
+                }
+
+                break;
+            case INamedTypeSymbol named:
+                yield return Normalize(named);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// The type a reference couples to. Interfaces and abstract classes keep their construction (<c>IHandler&lt;Order&gt;</c>)
+    /// so ports resolve to implementations of exactly that construction. Any other type is taken as its generic
+    /// definition, and a nested type as its outermost containing type: using <c>Receipts.Builder</c> couples to
+    /// <c>Receipts</c>, never to an unrelated top-level <c>Builder</c>.
+    /// </summary>
+    public static INamedTypeSymbol Normalize(INamedTypeSymbol type)
+    {
+        if (IsSeam(type))
+        {
+            return type;
+        }
+
+        var outermost = type.OriginalDefinition;
+        while (outermost.ContainingType is { } outer)
+        {
+            outermost = outer.OriginalDefinition;
+        }
+
+        return outermost;
+    }
+
+    /// <summary>
+    /// An interface or abstract class: a dependency on it resolves to the concrete classes behind it. An abstract
+    /// record is a data hierarchy (LabelSegment → LiteralSegment, PlaceholderSegment), not a seam.
+    /// </summary>
+    public static bool IsSeam(INamedTypeSymbol type) =>
+        type.TypeKind == TypeKind.Interface
+        || (type.TypeKind == TypeKind.Class && type.IsAbstract && !type.IsStatic && !type.IsRecord);
+}