@phuc1403/musketeer 0.9.0 → 0.11.0

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

@@ -0,0 +1,72 @@
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>extract &lt;repoPath&gt; [--out &lt;components.json&gt;]</c>: loads the repo and writes the deterministic extraction.
+/// Progress and warnings go to <c>errors</c> (stderr); the artifact goes to the --out file.
+/// Exit codes: 0 written, 1 usage, 2 the target repo or its config could not be loaded, 4 candidates not classified
+/// in the repo config yet (one <c>unclassified &lt;type&gt;</c> line each; nothing is written).
+/// </summary>
+public static class ExtractCommand
+{
+    public const string Usage = "usage: LogicalComponents extract <repoPath> [--out <components.json>]";
+
+    public static async Task<int> RunAsync(string[] args, TextWriter errors)
+    {
+        if (args is not [var repoPath, ..] || !TryParseOut(args[1..], out var outPath))
+        {
+            await errors.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        try
+        {
+            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, log: errors);
+            await errors.WriteLineAsync($"Loaded {loaded.ProjectNames.Count} projects from {loaded.Source}.");
+
+            var result = await CouplingResolver.ExtractAsync(loaded, ExtractConfig.Load(loaded.RepoRoot));
+            foreach (var warning in result.Warnings)
+            {
+                await errors.WriteLineAsync($"warning: {warning}");
+            }
+
+            Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(outPath))!);
+            await File.WriteAllBytesAsync(outPath, ComponentsFile.Serialize(result));
+            await errors.WriteLineAsync(
+                $"{result.Components.Count} components, {result.ExternalNodes.Count} ports, {result.Edges.Count} edges, "
+                + $"{result.Warnings.Count} warnings -> {Path.GetFullPath(outPath)}");
+            return 0;
+        }
+        catch (UnclassifiedCandidatesException e)
+        {
+            foreach (var type in e.Types)
+            {
+                await errors.WriteLineAsync($"unclassified {type}");
+            }
+
+            await errors.WriteLineAsync($"{e.Message}: run the classify step, review it, then extract again.");
+            return 4;
+        }
+        catch (Exception e) when (e is DirectoryNotFoundException or WorkspaceLoadException or ExtractConfigException)
+        {
+            await errors.WriteLineAsync(e.Message);
+            return 2;
+        }
+        catch (Exception e)
+        {
+            // Anything else (I/O, access, build host) is still a load failure: report it, don't crash with a stack trace.
+            await errors.WriteLineAsync($"Unexpected error while extracting {repoPath}: {e.Message}");
+            return 2;
+        }
+    }
+
+    private static bool TryParseOut(string[] options, out string outPath)
+    {
+        outPath = "components.json";
+        return options switch
+        {
+            [] => true,
+            ["--out", var path] => (outPath = path) is not null,
+            _ => false,
+        };
+    }
+}

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

@@ -0,0 +1,79 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace LogicalComponents;
+
+/// <summary>A config file in the target repo that could not be read, or contradicts itself.</summary>
+public sealed class ExtractConfigException(string message) : Exception(message);
+
+/// <summary>Candidates the repo config does not classify yet: extract refuses to guess.</summary>
+public sealed class UnclassifiedCandidatesException(IReadOnlyList<string> types)
+    : Exception($"{types.Count} candidate(s) not classified in {ExtractConfig.FileName}")
+{
+    public IReadOnlyList<string> Types { get; } = types;
+}
+
+/// <summary>
+/// The frozen classification in <c>logical-components.json</c> at the repo root: every candidate class is listed, by
+/// full metadata name, either as a component or as a helper (with the reason it is not a component). An LLM proposes
+/// the entries once and a person reviews them; extract only ever reads this file, so the same code and the same file
+/// always give the same components.
+/// </summary>
+public sealed record ExtractConfig(IReadOnlyList<string> Components, IReadOnlyDictionary<string, string> Helpers)
+{
+    public const string FileName = "logical-components.json";
+
+    public static ExtractConfig Empty { get; } = new([], new Dictionary<string, string>());
+
+    private static readonly JsonSerializerOptions Options = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+        // A misspelt key ("helper") must fail rather than silently classify nothing.
+        UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
+    };
+
+    public bool IsClassified(string fullName) => Helpers.ContainsKey(fullName) || Components.Contains(fullName);
+
+    public static ExtractConfig Load(string repoRoot)
+    {
+        var path = Path.Combine(repoRoot, FileName);
+        if (!File.Exists(path))
+        {
+            return Empty;
+        }
+
+        ConfigFile? file;
+        try
+        {
+            file = JsonSerializer.Deserialize<ConfigFile>(File.ReadAllText(path), Options);
+        }
+        catch (JsonException e)
+        {
+            throw new ExtractConfigException($"Invalid {FileName}: {e.Message}");
+        }
+
+        if (file?.Exclude is not null || file?.Include is not null)
+        {
+            throw new ExtractConfigException(
+                $"Invalid {FileName}: 'exclude'/'include' were replaced by 'components' and 'helpers' "
+                + "(full type names); re-run the classify step to regenerate it.");
+        }
+
+        var components = file?.Components ?? [];
+        var helpers = file?.Helpers ?? [];
+        var both = components.Where(helpers.ContainsKey).Distinct().Order(StringComparer.Ordinal).ToList();
+        if (both.Count > 0)
+        {
+            throw new ExtractConfigException(
+                $"Invalid {FileName}: {string.Join(", ", both.Select(n => $"'{n}'"))} is in both components and helpers.");
+        }
+
+        return new ExtractConfig(components, helpers);
+    }
+
+    // Exclude and Include are read only to reject a file written for the old format with a useful message.
+    private sealed record ConfigFile(
+        string[]? Components, Dictionary<string, string>? Helpers, string[]? Exclude, string[]? Include);
+}

package/template/.claude/skills/logical-components/scripts/LogicalComponents/LogicalComponents.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <OutputType>Exe</OutputType>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.9.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="5.9.0" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,73 @@
+using System.Text;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Writes the final document: <c># Logical Components</c> (one section per component, sorted by display name, each
+/// responsibility with its citation) and <c># Coupling</c> (a legend, then a Mermaid flowchart of the extracted edges).
+/// Everything but the responsibility text comes from the deterministic extraction; the output has LF line endings and no
+/// timestamp.
+/// Call only with responsibilities that passed <see cref="ResponsibilityValidation"/>.
+/// </summary>
+public static class MarkdownRenderer
+{
+    /// <summary>
+    /// How to read the diagram, so incoming and outgoing arrows are not read backwards, and what it leaves out, so an
+    /// entry point with no incoming arrow is not mistaken for dead code.
+    /// </summary>
+    private const string Legend =
+        "`A --> B` means A depends on B: it calls, creates, holds or inherits from B. A component's incoming arrows are its "
+        + "afferent coupling, its outgoing arrows its efferent coupling. Only components in `*.Application` and "
+        + "`*.Infrastructure` projects are drawn; callers in other projects, such as the host, are not shown.";
+
+    public static string Render(
+        ExtractResult extraction, IReadOnlyDictionary<string, IReadOnlyList<Responsibility>> responsibilities)
+    {
+        var md = new StringBuilder();
+        md.Append("# Logical Components\n\n");
+        foreach (var component in extraction.Components
+                     .OrderBy(c => c.Name, StringComparer.Ordinal)
+                     .ThenBy(c => c.Id, StringComparer.Ordinal))
+        {
+            md.Append($"## {component.Name}\n\n");
+            md.Append($"`{SymbolNames.ReadableFullName(component.Type)}`\n\n");
+            foreach (var responsibility in responsibilities[component.Id])
+            {
+                md.Append($"- {responsibility.Text.Trim()} (`{Citation.Parse(responsibility.Cite)}`)\n");
+            }
+
+            md.Append('\n');
+        }
+
+        // ELK lays out a large flowchart far more readably than Mermaid's default dagre.
+        md.Append("# Coupling\n\n").Append(Legend).Append("\n\n```mermaid\n%%{init: {\"layout\": \"elk\"}}%%\nflowchart LR\n");
+        var nodes = extraction.Components
+            .Select(c => (c.Id, c.Name))
+            .Concat(extraction.ExternalNodes.Select(n => (n.Id, n.Name)))
+            .OrderBy(n => n.Id, StringComparer.Ordinal);
+        foreach (var (id, name) in nodes)
+        {
+            md.Append($"    {NodeId(id)}[\"{Escape(name)}\"]\n");
+        }
+
+        // A --> B: A depends on B (efferent for A, afferent for B). How A reaches B (di, new, static, inherits) is not
+        // drawn; it stays in components.json.
+        foreach (var edge in extraction.Edges)
+        {
+            md.Append($"    {NodeId(edge.From)} --> {NodeId(edge.To)}\n");
+        }
+
+        md.Append("```\n");
+        return md.ToString();
+    }
+
+    // Mermaid node labels are double-quoted; a literal quote is written as an entity.
+    private static string Escape(string label) => label.Replace("\"", "#quot;");
+
+    /// <summary>
+    /// A Mermaid-safe node id: prefixed so a component called <c>end</c>, <c>graph</c> or <c>class</c> is never read as a
+    /// keyword, and reduced to letters, digits and underscores so a module name with spaces cannot break a line.
+    /// </summary>
+    private static string NodeId(string id) =>
+        "n_" + new string(id.Select(c => char.IsAsciiLetterOrDigit(c) ? c : '_').ToArray());
+}

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

@@ -0,0 +1,203 @@
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Follows what a component's code uses until it lands on another component. A use of a member of:
+/// <list type="bullet">
+/// <item>a component is an edge to it;</item>
+/// <item>an interface or abstract class (a seam) goes on to the member that runs in each implementation of the
+/// construction used (see <see cref="SeamDispatch"/>);</item>
+/// <item>any other type of the repo (a helper, a record, a non-candidate) is seen through: the code that runs for that
+/// use is walked the same way, with the helper's type parameters bound to the use's type arguments (see
+/// <see cref="TypeMap"/>). It is walked per member and per accessor, so reading one property never couples to what
+/// another member or the setter calls, and compiler-written record members run nothing.</item>
+/// </list>
+/// Framework and library members end the walk. The kind of an edge is the kind of the last use; its citation is the
+/// line in the component where the chain starts; <c>via</c> names the seams and seen-through types on the first path
+/// found (members already walked for a component are not walked again). The helper code walked is the component's
+/// <c>reaches</c>.
+/// </summary>
+public sealed class MemberUseResolution(LoadedWorkspace loaded, IReadOnlySet<string> components, PortResolution ports)
+{
+    public sealed record RawEdge(string From, string To, string Kind, IReadOnlyList<string> Via, string File, int Line);
+
+    /// <summary>The edges a component's code leads to, and the helper code it runs on the way (sorted, distinct).</summary>
+    public sealed record Resolution(List<RawEdge> Edges, List<SourceSpan> Reaches);
+
+    // Shared by every component's walk: what a piece of syntax uses never changes within one loaded solution.
+    private readonly Dictionary<SyntaxNode, List<MemberUses.MemberUse>> _uses = [];
+    private readonly Dictionary<INamedTypeSymbol, bool> _repoSource = new(SymbolEqualityComparer.Default);
+
+    /// <summary>
+    /// The edges from <paramref name="from"/> reached by <paramref name="uses"/>. <paramref name="self"/> holds the
+    /// component and the base classes whose code counts as its own: uses of those are not coupling.
+    /// </summary>
+    public async Task<Resolution> ResolveAsync(
+        string from, IReadOnlySet<string> self, IEnumerable<MemberUses.MemberUse> uses, CancellationToken cancellationToken)
+    {
+        var walk = new Walk(from, self);
+        foreach (var use in uses)
+        {
+            await ResolveUseAsync(use.Member, use.Kind, [], use.File, use.Line, TypeMap.Empty, walk, cancellationToken);
+        }
+
+        return new Resolution(
+            walk.Edges,
+            walk.Reaches.OrderBy(s => s.File, StringComparer.Ordinal).ThenBy(s => s.Start).ThenBy(s => s.End).ToList());
+    }
+
+    // One component's walk: members already seen through (for the same type bindings) are not walked again, which also
+    // ends cycles.
+    private sealed class Walk(string from, IReadOnlySet<string> self)
+    {
+        public string From { get; } = from;
+        public IReadOnlySet<string> Self { get; } = self;
+        public HashSet<string> Visited { get; } = new(StringComparer.Ordinal);
+        public List<RawEdge> Edges { get; } = [];
+        public HashSet<SourceSpan> Reaches { get; } = [];
+    }
+
+    private async Task ResolveUseAsync(
+        ISymbol member,
+        string kind,
+        ImmutableList<string> via,
+        string file,
+        int line,
+        TypeMap map,
+        Walk walk,
+        CancellationToken cancellationToken)
+    {
+        // A C# 14 extension member belongs to the static class around its extension block.
+        var declaring = member.ContainingType is { IsExtension: true } block ? block.ContainingType : member.ContainingType;
+        if (declaring is null)
+        {
+            return;
+        }
+
+        if (map.Substitute(declaring) is INamedTypeSymbol bound)
+        {
+            declaring = bound;
+        }
+
+        var owner = EdgeExtraction.Normalize(declaring.OriginalDefinition);
+        if (!IsRepo(owner) || walk.Self.Contains(SymbolNames.FullName(owner)))
+        {
+            return;
+        }
+
+        if (components.Contains(SymbolNames.FullName(owner)))
+        {
+            walk.Edges.Add(new RawEdge(walk.From, SymbolNames.FullName(owner), kind, via, file, line));
+            return;
+        }
+
+        if (EdgeExtraction.IsSeam(declaring) && !member.IsStatic && kind != EdgeExtraction.New)
+        {
+            foreach (var implementation in await ports.ImplementationsAsync(declaring, cancellationToken))
+            {
+                if (SeamDispatch.ImplementationOf(implementation, declaring, member) is not { } runs)
+                {
+                    continue;
+                }
+
+                // An inherited default body lives on the seam itself: walk it rather than resolve the seam again.
+                if (runs.ContainingType is { } runsIn && EdgeExtraction.IsSeam(runsIn))
+                {
+                    await SeeThroughAsync(runs, kind, via.Add(declaring.Name), file, line, map, walk, cancellationToken);
+                }
+                else
+                {
+                    await ResolveUseAsync(runs, kind, via.Add(declaring.Name), file, line, TypeMap.Empty, walk, cancellationToken);
+                }
+            }
+
+            return;
+        }
+
+        await SeeThroughAsync(member, kind, via.Add(owner.Name), file, line, map, walk, cancellationToken);
+    }
+
+    private async Task SeeThroughAsync(
+        ISymbol member,
+        string kind,
+        ImmutableList<string> via,
+        string file,
+        int line,
+        TypeMap map,
+        Walk walk,
+        CancellationToken cancellationToken)
+    {
+        // Compiler-written members (a record's ToString/Equals/Deconstruct, an auto-property accessor) run nothing of the
+        // type's own code; their declaring syntax is the whole type, which must not be walked. Constructors still run
+        // initializers. Using an instance field runs no code: its initializer ran when the object was constructed.
+        if ((member.IsImplicitlyDeclared && kind != EdgeExtraction.New) || member is IFieldSymbol { IsStatic: false })
+        {
+            return;
+        }
+
+        var inner = map.For(member);
+        var key = (kind == EdgeExtraction.New ? "new " : "") + SymbolNames.MemberId(member) + "|" + inner.Key;
+        if (!walk.Visited.Add(key))
+        {
+            return;
+        }
+
+        var (roots, runsImplicitBase) = kind == EdgeExtraction.New && member is IMethodSymbol constructor
+            ? WalkRoots.Construction(constructor)
+            : (WalkRoots.Body(member), false);
+        Record(roots, walk);
+
+        foreach (var root in roots)
+        {
+            foreach (var use in await UsesAsync(root, cancellationToken))
+            {
+                await ResolveUseAsync(use.Member, use.Kind, via, file, line, inner, walk, cancellationToken);
+            }
+        }
+
+        if (runsImplicitBase
+            && member.ContainingType.BaseType?.InstanceConstructors.FirstOrDefault(c => c.Parameters.Length == 0) is { } baseConstructor)
+        {
+            await ResolveUseAsync(baseConstructor, EdgeExtraction.New, via, file, line, inner, walk, cancellationToken);
+        }
+    }
+
+    // The walked helper code becomes citable for the component; a parameter declares a value and runs nothing.
+    private void Record(IEnumerable<SyntaxNode> roots, Walk walk)
+    {
+        foreach (var root in roots.Where(r => r is not (ParameterSyntax or ParameterListSyntax)))
+        {
+            var (sourceKind, relative) = CitableSource.Classify(loaded, root.SyntaxTree);
+            if (sourceKind == CitableSource.Kind.InRepo)
+            {
+                var lines = root.GetLocation().GetLineSpan();
+                walk.Reaches.Add(new SourceSpan(relative, lines.StartLinePosition.Line + 1, lines.EndLinePosition.Line + 1));
+            }
+        }
+    }
+
+    private async Task<List<MemberUses.MemberUse>> UsesAsync(SyntaxNode root, CancellationToken cancellationToken)
+    {
+        if (!_uses.TryGetValue(root, out var uses))
+        {
+            uses = await MemberUses.ReadAsync([root], loaded, cancellationToken);
+            _uses[root] = uses;
+        }
+
+        return uses;
+    }
+
+    private bool IsRepo(INamedTypeSymbol type)
+    {
+        if (!_repoSource.TryGetValue(type, out var isRepo))
+        {
+            isRepo = CitableSource.IsRepoSource(type, loaded);
+            _repoSource[type] = isRepo;
+        }
+
+        return isRepo;
+    }
+}

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

@@ -0,0 +1,155 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Reads what a piece of code uses, as members: <c>new</c> (the constructor an object creation, a <c>: this(...)</c> /
+/// <c>: base(...)</c> initializer or a primary-constructor base call runs), <c>static</c> (a static member, an extension
+/// method or C# 14 extension member, a user-defined operator or conversion) and <c>call</c> (an instance member used on
+/// any receiver, an indexer, the enumerator a <c>foreach</c> runs). A property or indexer use is the accessor that
+/// actually runs: a read is the getter, an assignment the setter, a compound assignment or increment both. Only
+/// citable source is read, so generator output never contributes. What a use couples to is decided by
+/// <see cref="MemberUseResolution"/>.
+/// </summary>
+public static class MemberUses
+{
+    /// <summary>One use of <see cref="Member"/>, at a repo-relative file and 1-based line.</summary>
+    public sealed record MemberUse(ISymbol Member, string Kind, string File, int Line);
+
+    /// <summary>Every member use inside the given syntax nodes, in source order. Nodes outside the repo are skipped.</summary>
+    public static async Task<List<MemberUse>> ReadAsync(
+        IEnumerable<SyntaxNode> roots, LoadedWorkspace loaded, CancellationToken cancellationToken)
+    {
+        var uses = new List<MemberUse>();
+        foreach (var root in roots)
+        {
+            var (kind, file) = CitableSource.Classify(loaded, root.SyntaxTree);
+            if (kind != CitableSource.Kind.InRepo || loaded.Solution.GetDocument(root.SyntaxTree) is not { } document)
+            {
+                continue;
+            }
+
+            var model = await document.GetSemanticModelAsync(cancellationToken)
+                ?? throw new InvalidOperationException($"No semantic model for {file}");
+            foreach (var node in root.DescendantNodesAndSelf())
+            {
+                var line = node.GetLocation().GetLineSpan().StartLinePosition.Line + 1;
+                uses.AddRange(Uses(node, model, cancellationToken).Select(u => new MemberUse(u.Member, u.Kind, file, line)));
+            }
+        }
+
+        return uses;
+    }
+
+    private static IEnumerable<(ISymbol Member, string Kind)> Uses(SyntaxNode node, SemanticModel model, CancellationToken token)
+    {
+        ISymbol? Symbol() => model.GetSymbolInfo(node, token).Symbol;
+
+        switch (node)
+        {
+            case BaseObjectCreationExpressionSyntax or ConstructorInitializerSyntax or PrimaryConstructorBaseTypeSyntax:
+                if (Symbol() is IMethodSymbol constructor)
+                {
+                    yield return (constructor, EdgeExtraction.New);
+                }
+
+                break;
+            case SimpleNameSyntax name when !IsInsideNameOf(name, model):
+                foreach (var use in Classify(Symbol(), name))
+                {
+                    yield return use;
+                }
+
+                break;
+            case ElementAccessExpressionSyntax when Symbol() is IPropertySymbol indexer:
+                foreach (var accessor in AccessorsThatRun(indexer, node))
+                {
+                    yield return (accessor, EdgeExtraction.Call);
+                }
+
+                break;
+            case BinaryExpressionSyntax or PrefixUnaryExpressionSyntax or PostfixUnaryExpressionSyntax
+                or CastExpressionSyntax or AssignmentExpressionSyntax
+                when Symbol() is IMethodSymbol { MethodKind: MethodKind.UserDefinedOperator or MethodKind.Conversion } op:
+                yield return (op, EdgeExtraction.Static);
+                break;
+            case CommonForEachStatementSyntax loop when model.GetForEachStatementInfo(loop).GetEnumeratorMethod is { } enumerator:
+                yield return (enumerator, enumerator.IsStatic ? EdgeExtraction.Static : EdgeExtraction.Call);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// A symbol a name refers to, as uses: static or extension members are <c>static</c> (a classic extension method is
+    /// seen as its unreduced static form), other members are <c>call</c>, a property is the accessors that run. Locals,
+    /// parameters, types, namespaces and consts (copied into the caller at compile time) are not uses.
+    /// </summary>
+    private static IEnumerable<(ISymbol, string)> Classify(ISymbol? symbol, SyntaxNode usage)
+    {
+        var kind = symbol is not null && (symbol.IsStatic || symbol.ContainingType is { IsExtension: true })
+            ? EdgeExtraction.Static
+            : EdgeExtraction.Call;
+        switch (symbol)
+        {
+            case IFieldSymbol { IsConst: true }:
+            case IMethodSymbol { MethodKind: MethodKind.LocalFunction or MethodKind.AnonymousFunction }:
+                break;
+            case IMethodSymbol { ReducedFrom: { } extension }:
+                yield return (extension, EdgeExtraction.Static);
+                break;
+            case IPropertySymbol property:
+                foreach (var accessor in AccessorsThatRun(property, usage))
+                {
+                    yield return (accessor, kind);
+                }
+
+                break;
+            case IMethodSymbol or IFieldSymbol or IEventSymbol:
+                yield return (symbol, kind);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// The accessors a property or indexer use runs, from where it stands: the target of <c>=</c> (including an object
+    /// initializer) runs the setter; a compound assignment, <c>++</c>/<c>--</c>, or a <c>ref</c>/<c>out</c> argument runs
+    /// both; anything else is a read and runs the getter. An accessor the property does not have runs nothing.
+    /// </summary>
+    private static IEnumerable<IMethodSymbol> AccessorsThatRun(IPropertySymbol property, SyntaxNode usage)
+    {
+        // The whole access expression: `a.B` for the name B, `a?.B` for a conditional access, the name itself otherwise.
+        var access = usage.Parent switch
+        {
+            MemberAccessExpressionSyntax member when member.Name == usage => member,
+            MemberBindingExpressionSyntax binding => (SyntaxNode)binding,
+            _ => usage,
+        };
+
+        var (reads, writes) = access.Parent switch
+        {
+            AssignmentExpressionSyntax assignment when assignment.Left == access =>
+                (!assignment.IsKind(SyntaxKind.SimpleAssignmentExpression), true),
+            PrefixUnaryExpressionSyntax or PostfixUnaryExpressionSyntax => (true, true),
+            ArgumentSyntax { RefKindKeyword.RawKind: not 0 } => (true, true),
+            _ => (true, false),
+        };
+
+        if (reads && property.GetMethod is { } getter)
+        {
+            yield return getter;
+        }
+
+        if (writes && property.SetMethod is { } setter)
+        {
+            yield return setter;
+        }
+    }
+
+    // nameof(Foo.Bar) mentions a member without using it.
+    private static bool IsInsideNameOf(SyntaxNode node, SemanticModel model) =>
+        node.Ancestors().OfType<InvocationExpressionSyntax>().Any(invocation =>
+            invocation.Expression is IdentifierNameSyntax { Identifier.Text: "nameof" }
+            && model.GetSymbolInfo(invocation).Symbol is null);
+}

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

@@ -0,0 +1,75 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.FindSymbols;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Maps a seam (an interface or abstract class) to the concrete classes behind it in the loaded solution. Test
+/// projects were removed at load time, so test doubles never appear. Asking the type system rather than parsing DI
+/// registrations covers every registration style (instance, factory, forwarding) at once.
+/// A constructed generic seam (<c>IHandler&lt;Order&gt;</c>) resolves only to classes implementing exactly that construction,
+/// or an open generic one (<c>LoggingHandler&lt;T&gt; : IHandler&lt;T&gt;</c>). Results are cached per construction and sorted.
+/// </summary>
+public sealed class PortResolution(Solution solution)
+{
+    private readonly Dictionary<string, IReadOnlyList<INamedTypeSymbol>> _cache = new(StringComparer.Ordinal);
+
+    public async Task<IReadOnlyList<INamedTypeSymbol>> ImplementationsAsync(
+        INamedTypeSymbol seam, CancellationToken cancellationToken)
+    {
+        var key = Display(seam);
+        if (_cache.TryGetValue(key, out var cached))
+        {
+            return cached;
+        }
+
+        var definition = seam.OriginalDefinition;
+        IEnumerable<INamedTypeSymbol> found = definition.TypeKind == TypeKind.Interface
+            ? (await SymbolFinder.FindImplementationsAsync(definition, solution, cancellationToken: cancellationToken))
+                .OfType<INamedTypeSymbol>()
+            : await SymbolFinder.FindDerivedClassesAsync(definition, solution, transitive: true, cancellationToken: cancellationToken);
+
+        var implementations = found
+            .Where(t => t.TypeKind == TypeKind.Class && !t.IsAbstract)
+            .Select(t => t.OriginalDefinition)
+            .Where(t => ImplementsConstruction(t, seam))
+            .DistinctBy(SymbolNames.FullName)
+            .OrderBy(SymbolNames.FullName, StringComparer.Ordinal)
+            .ToList();
+        _cache[key] = implementations;
+        return implementations;
+    }
+
+    private static bool ImplementsConstruction(INamedTypeSymbol implementation, INamedTypeSymbol seam)
+    {
+        if (!seam.IsGenericType || seam.TypeArguments.All(a => a is ITypeParameterSymbol))
+        {
+            return true;
+        }
+
+        var definition = SymbolNames.FullName(seam.OriginalDefinition);
+        var wanted = Display(seam);
+        return Supertypes(implementation, seam.TypeKind).Any(s =>
+            SymbolNames.FullName(s.OriginalDefinition) == definition
+            && (Display(s) == wanted || s.TypeArguments.Any(a => a is ITypeParameterSymbol)));
+    }
+
+    private static IEnumerable<INamedTypeSymbol> Supertypes(INamedTypeSymbol type, TypeKind seamKind)
+    {
+        if (seamKind == TypeKind.Interface)
+        {
+            return type.AllInterfaces;
+        }
+
+        var bases = new List<INamedTypeSymbol>();
+        for (var current = type.BaseType; current is not null; current = current.BaseType)
+        {
+            bases.Add(current);
+        }
+
+        return bases;
+    }
+
+    // Compared as text: symbols of the same type seen from two projects' compilations are not always the same instance.
+    private static string Display(ITypeSymbol type) => type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
+}