@phuc1403/musketeer 0.9.0 → 0.11.0

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

@@ -0,0 +1,59 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>Which member runs in an implementation when a member of a seam (interface or abstract class) is used.</summary>
+public static class SeamDispatch
+{
+    /// <summary>
+    /// The member that runs in <paramref name="implementation"/> when <paramref name="member"/> of
+    /// <paramref name="seam"/> (as constructed at the use) is used: the implementation of that exact construction of the
+    /// interface member (a class implementing <c>IHandler&lt;Ping&gt;</c> and <c>IHandler&lt;Pong&gt;</c> runs its Pong
+    /// member for a Pong use), else the one of an open construction; for an abstract class, the most derived override,
+    /// possibly the seam's own body.
+    /// </summary>
+    public static ISymbol? ImplementationOf(INamedTypeSymbol implementation, INamedTypeSymbol seam, ISymbol member)
+    {
+        var wanted = SymbolNames.MemberId(member);
+        if (seam.TypeKind == TypeKind.Interface)
+        {
+            var definition = SymbolNames.FullName(seam.OriginalDefinition);
+            var constructions = implementation.AllInterfaces
+                .Where(i => SymbolNames.FullName(i.OriginalDefinition) == definition)
+                .ToList();
+            var exact = constructions.Where(i => Display(i) == Display(seam)).ToList();
+            return (exact.Count > 0 ? exact : constructions)
+                .SelectMany(i => i.GetMembers(member.Name))
+                .Where(candidate => SymbolNames.MemberId(candidate) == wanted)
+                .Select(implementation.FindImplementationForInterfaceMember)
+                .FirstOrDefault(found => found is not null);
+        }
+
+        for (var type = implementation; type is not null; type = type.BaseType)
+        {
+            foreach (var candidate in type.GetMembers(member.Name))
+            {
+                for (var overridden = candidate; overridden is not null; overridden = Overridden(overridden))
+                {
+                    if (SymbolNames.MemberId(overridden) == wanted)
+                    {
+                        return candidate;
+                    }
+                }
+            }
+        }
+
+        return null;
+    }
+
+    private static ISymbol? Overridden(ISymbol symbol) => symbol switch
+    {
+        IMethodSymbol method => method.OverriddenMethod,
+        IPropertySymbol property => property.OverriddenProperty,
+        IEventSymbol @event => @event.OverriddenEvent,
+        _ => null,
+    };
+
+    // Compared as text: symbols of the same type seen from two projects' compilations are not the same instance.
+    private static string Display(ITypeSymbol type) => type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
+}

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

@@ -0,0 +1,53 @@
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>Stable textual names for symbols, independent of nullable annotations and of where the repo is checked out.</summary>
+public static class SymbolNames
+{
+    // No miscellaneous options: in particular no nullable '?' suffix, so IServiceCollection? == IServiceCollection.
+    private static readonly SymbolDisplayFormat Qualified = new(
+        typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypesAndNamespaces);
+
+    /// <summary><c>Microsoft.Extensions.DependencyInjection.IServiceCollection</c>, whatever its nullability.</summary>
+    public static string QualifiedName(ITypeSymbol type) => type.ToDisplayString(Qualified);
+
+    /// <summary>
+    /// Full metadata name: namespace plus metadata name (generic arity kept, e.g. <c>Ns.Cache`1</c>). A nested type
+    /// carries its containing types (<c>Ns.Receipts+Builder</c>), so it can never collide with a top-level namesake.
+    /// </summary>
+    public static string FullName(INamedTypeSymbol type) =>
+        type.ContainingType is { } outer
+            ? $"{FullName(outer)}+{type.MetadataName}"
+            : type.ContainingNamespace.IsGlobalNamespace
+                ? type.MetadataName
+                : $"{type.ContainingNamespace.ToDisplayString()}.{type.MetadataName}";
+
+    /// <summary>
+    /// A member's identity across compilations (symbols of one member seen from two projects are not the same instance):
+    /// the documentation-comment id of its definition, e.g. <c>M:Ns.Handler`1.Handle(`0)</c>.
+    /// </summary>
+    public static string MemberId(ISymbol symbol) =>
+        symbol.OriginalDefinition.GetDocumentationCommentId() ?? symbol.OriginalDefinition.ToDisplayString();
+
+    /// <summary>A name safe as a diagram id: <c>Ns.Receipts+Cache`1</c> → <c>Ns_Receipts_Cache_1</c>.</summary>
+    public static string ToIdentifier(string fullName) =>
+        fullName.Replace('.', '_').Replace('+', '_').Replace('`', '_');
+
+    /// <summary>The simple name without arity: <c>Ns.Cache`1</c> → <c>Cache</c>, <c>Ns.Outer+Inner</c> → <c>Inner</c>.</summary>
+    public static string SimpleName(string fullName)
+    {
+        var name = fullName[(fullName.LastIndexOfAny(['.', '+']) + 1)..];
+        var tick = name.IndexOf('`');
+        return tick < 0 ? name : name[..tick];
+    }
+
+    /// <summary>The full name as a reader writes it: <c>Ns.Cache`1</c> → <c>Ns.Cache&lt;&gt;</c>, <c>`2</c> → <c>&lt;,&gt;</c>.</summary>
+    public static string ReadableFullName(string fullName)
+    {
+        var tick = fullName.LastIndexOf('`');
+        return tick < 0 || !int.TryParse(fullName[(tick + 1)..], out var arity)
+            ? fullName
+            : $"{fullName[..tick]}<{new string(',', arity - 1)}>";
+    }
+}

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

@@ -0,0 +1,75 @@
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// What a generic helper's type parameters stand for at the use being followed. Walking <c>Dispatch.Send&lt;T&gt;</c>
+/// for <c>Send(new Ping())</c> maps <c>T</c> to <c>Ping</c>, so the <c>ICommandHandler&lt;T&gt;</c> it calls is
+/// resolved as <c>ICommandHandler&lt;Ping&gt;</c> and reaches only the Ping handlers, not every handler.
+/// </summary>
+public sealed class TypeMap
+{
+    private readonly Dictionary<ITypeParameterSymbol, ITypeSymbol> _map;
+
+    private TypeMap(Dictionary<ITypeParameterSymbol, ITypeSymbol> map)
+    {
+        _map = map;
+        Key = string.Join(";", map
+            .Select(p => $"{p.Key.ContainingSymbol.ToDisplayString()}.{p.Key.Name}={p.Value.ToDisplayString()}")
+            .Order(StringComparer.Ordinal));
+    }
+
+    public static TypeMap Empty { get; } = new(new Dictionary<ITypeParameterSymbol, ITypeSymbol>(SymbolEqualityComparer.Default));
+
+    /// <summary>Stable text of the bindings: the same member walked for two different bindings is two walks.</summary>
+    public string Key { get; }
+
+    /// <summary>The type with every mapped type parameter replaced, inside generic arguments too.</summary>
+    public ITypeSymbol Substitute(ITypeSymbol type) => type switch
+    {
+        ITypeParameterSymbol parameter when _map.TryGetValue(parameter, out var bound) => bound,
+        INamedTypeSymbol { IsGenericType: true } named when named.TypeArguments.Any(Mentions) =>
+            named.OriginalDefinition.Construct([.. named.TypeArguments.Select(Substitute)]),
+        _ => type,
+    };
+
+    /// <summary>
+    /// The map for walking <paramref name="member"/>'s own code: the type parameters of its definition and of its
+    /// containing types, bound to the arguments this use supplies (read through this map, for nested generic helpers).
+    /// </summary>
+    public TypeMap For(ISymbol member)
+    {
+        var map = new Dictionary<ITypeParameterSymbol, ITypeSymbol>(SymbolEqualityComparer.Default);
+        void Bind(ImmutableArray<ITypeParameterSymbol> parameters, ImmutableArray<ITypeSymbol> arguments)
+        {
+            for (var i = 0; i < parameters.Length && i < arguments.Length; i++)
+            {
+                var argument = Substitute(arguments[i]);
+                if (!SymbolEqualityComparer.Default.Equals(parameters[i], argument))
+                {
+                    map[parameters[i]] = argument;
+                }
+            }
+        }
+
+        if (member is IMethodSymbol method)
+        {
+            Bind(method.OriginalDefinition.TypeParameters, method.TypeArguments);
+        }
+
+        for (var type = member.ContainingType; type is not null; type = type.ContainingType)
+        {
+            Bind(type.OriginalDefinition.TypeParameters, type.TypeArguments);
+        }
+
+        return map.Count == 0 ? Empty : new TypeMap(map);
+    }
+
+    private bool Mentions(ITypeSymbol type) => type switch
+    {
+        ITypeParameterSymbol parameter => _map.ContainsKey(parameter),
+        INamedTypeSymbol { IsGenericType: true } named => named.TypeArguments.Any(Mentions),
+        _ => false,
+    };
+}

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

@@ -0,0 +1,63 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// The syntax that runs when a member is used, for <see cref="MemberUseResolution"/> to walk. Always in (file, position)
+/// order, so the walk, and the first path it records, is the same on every checkout.
+/// </summary>
+public static class WalkRoots
+{
+    /// <summary>The declaration of a member: its body, accessor or initializer, from the implementing half if it is partial.</summary>
+    public static List<SyntaxNode> Body(ISymbol member) =>
+        Ordered(Implementation(member.OriginalDefinition).DeclaringSyntaxReferences.Select(r => r.GetSyntax()));
+
+    /// <summary>
+    /// What <c>new</c> runs: the constructor (for a primary constructor, only its parameter defaults and base call, never
+    /// the whole type) and the type's instance field and property initializers. <c>RunsImplicitBase</c> is set when the
+    /// constructor calls no <c>base(...)</c>/<c>this(...)</c> itself, so the base class's parameterless constructor runs.
+    /// </summary>
+    public static (List<SyntaxNode> Roots, bool RunsImplicitBase) Construction(IMethodSymbol constructor)
+    {
+        var roots = new List<SyntaxNode>();
+        var explicitChain = false;
+        foreach (var syntax in Implementation(constructor.OriginalDefinition).DeclaringSyntaxReferences.Select(r => r.GetSyntax()))
+        {
+            if (syntax is TypeDeclarationSyntax type)
+            {
+                var baseCall = type.BaseList?.Types.OfType<PrimaryConstructorBaseTypeSyntax>().FirstOrDefault();
+                explicitChain |= baseCall is not null;
+                roots.AddRange(new SyntaxNode?[] { type.ParameterList, baseCall }.OfType<SyntaxNode>());
+            }
+            else
+            {
+                explicitChain |= syntax is ConstructorDeclarationSyntax { Initializer: not null };
+                roots.Add(syntax);
+            }
+        }
+
+        foreach (var member in constructor.ContainingType.OriginalDefinition.GetMembers().Where(m => !m.IsStatic))
+        {
+            roots.AddRange(member.DeclaringSyntaxReferences.Select(r => r.GetSyntax()).Select(syntax => syntax switch
+            {
+                VariableDeclaratorSyntax { Initializer: { } initializer } => initializer,
+                PropertyDeclarationSyntax { Initializer: { } initializer } => initializer,
+                _ => null,
+            }).OfType<SyntaxNode>());
+        }
+
+        return (Ordered(roots), !explicitChain);
+    }
+
+    // A partial method, property or constructor is walked where its body is written.
+    private static ISymbol Implementation(ISymbol member) => member switch
+    {
+        IMethodSymbol { PartialImplementationPart: { } implementation } => implementation,
+        IPropertySymbol { PartialImplementationPart: { } implementation } => implementation,
+        _ => member,
+    };
+
+    private static List<SyntaxNode> Ordered(IEnumerable<SyntaxNode> roots) =>
+        roots.OrderBy(r => r.SyntaxTree.FilePath, StringComparer.Ordinal).ThenBy(r => r.SpanStart).ToList();
+}

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

@@ -0,0 +1,227 @@
+using System.Diagnostics;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.MSBuild;
+
+namespace LogicalComponents;
+
+/// <summary>A target repo that could not be restored or loaded into a Roslyn workspace.</summary>
+public sealed class WorkspaceLoadException(string message) : Exception(message);
+
+/// <summary>
+/// A loaded repo: the Roslyn solution reduced to one C# source project per project file, plus where it came from.
+/// Owns the workspace (and its out-of-process build host), so dispose it when done.
+/// </summary>
+public sealed class LoadedWorkspace(MSBuildWorkspace workspace, Solution solution, string repoRoot, string source)
+    : IDisposable
+{
+    public Solution Solution { get; } = solution;
+
+    /// <summary>Absolute repo root; every path written to output is made relative to it.</summary>
+    public string RepoRoot { get; } = repoRoot;
+
+    /// <summary>The solution file name, or the glob the loader fell back to.</summary>
+    public string Source { get; } = source;
+
+    public IReadOnlyList<string> ProjectNames { get; } =
+        solution.Projects.Select(p => p.Name).Order(StringComparer.Ordinal).ToList();
+
+    public void Dispose() => workspace.Dispose();
+}
+
+/// <summary>
+/// Loads a repo's source projects into a Roslyn workspace. The top-level solution is preferred; the csproj files
+/// are used only when there is no solution or it contains no source projects. A solution that exists but fails
+/// to open is an error, never a silent switch to a different project set.
+/// </summary>
+public static class WorkspaceLoader
+{
+    private static readonly TimeSpan RestoreTimeout = TimeSpan.FromMinutes(10);
+
+    public static async Task<LoadedWorkspace> LoadAsync(string repoPath, bool restore = true, TextWriter? log = null)
+    {
+        var repoRoot = Path.GetFullPath(repoPath);
+        if (!Directory.Exists(repoRoot))
+        {
+            throw new DirectoryNotFoundException($"Repository path not found: {repoRoot}");
+        }
+
+        log ??= TextWriter.Null;
+
+        var solutionFile = FindSolutionFile(repoRoot);
+        if (solutionFile is not null)
+        {
+            var name = Path.GetFileName(solutionFile);
+            var loaded = await LoadAsync(repoRoot, name, [solutionFile], restore, log,
+                (workspace, file) => workspace.OpenSolutionAsync(file));
+            if (loaded.Solution.Projects.Any())
+            {
+                return loaded;
+            }
+
+            loaded.Dispose();
+            log.WriteLine($"{name} contains no C# source projects; falling back to project files.");
+        }
+
+        var (projectFiles, glob) = FindProjectFiles(repoRoot);
+        if (projectFiles.Count == 0)
+        {
+            throw new WorkspaceLoadException($"No solution and no C# source project found under {repoRoot}");
+        }
+
+        return await LoadAsync(repoRoot, glob, projectFiles, restore, log, async (workspace, file) =>
+        {
+            // Opening a project also loads its references; skip ones already pulled in that way.
+            if (workspace.CurrentSolution.Projects.All(p => !PathsEqual(p.FilePath, file)))
+            {
+                await workspace.OpenProjectAsync(file);
+            }
+        });
+    }
+
+    /// <summary>Restores and opens each entry file, then reduces the result to source projects.</summary>
+    private static async Task<LoadedWorkspace> LoadAsync(
+        string repoRoot, string source, IReadOnlyList<string> entryFiles, bool restore, TextWriter log,
+        Func<MSBuildWorkspace, string, Task> open)
+    {
+        var workspace = MSBuildWorkspace.Create();
+        try
+        {
+            var failures = new List<string>();
+            workspace.RegisterWorkspaceFailedHandler(e =>
+            {
+                if (e.Diagnostic.Kind == WorkspaceDiagnosticKind.Failure)
+                {
+                    failures.Add(e.Diagnostic.Message);
+                }
+                else
+                {
+                    log.WriteLine($"warning: {e.Diagnostic.Message}");
+                }
+            });
+
+            foreach (var file in entryFiles)
+            {
+                if (restore)
+                {
+                    await RestoreAsync(file, repoRoot);
+                }
+
+                await open(workspace, file);
+            }
+
+            if (failures.Count > 0)
+            {
+                throw new WorkspaceLoadException(
+                    $"Loading {source} failed:{Environment.NewLine}  " + string.Join(Environment.NewLine + "  ", failures));
+            }
+
+            return new LoadedWorkspace(workspace, KeepSourceProjects(workspace.CurrentSolution, repoRoot), repoRoot, source);
+        }
+        catch (Exception e)
+        {
+            workspace.Dispose();
+            throw e is WorkspaceLoadException ? e : new WorkspaceLoadException($"Loading {source} failed: {e.Message}");
+        }
+    }
+
+    /// <summary>
+    /// Drops non-C# and test projects, and keeps one project per multi-targeted project file: the highest target
+    /// framework, renamed without its <c>(tfm)</c> suffix, so every type is seen exactly once.
+    /// </summary>
+    private static Solution KeepSourceProjects(Solution solution, string repoRoot)
+    {
+        foreach (var byFile in solution.Projects.GroupBy(p => p.FilePath ?? "", StringComparer.OrdinalIgnoreCase))
+        {
+            var projects = byFile.ToList();
+            var isSource = byFile.Key != ""
+                && projects[0].Language == LanguageNames.CSharp
+                && !ProjectFilters.IsTestProject(Path.GetRelativePath(repoRoot, byFile.Key), File.ReadAllText(byFile.Key));
+            var kept = isSource
+                ? projects.MaxBy(p => ProjectFilters.TargetFrameworkRank(p.Name))
+                : null;
+
+            foreach (var project in projects.Where(p => p != kept))
+            {
+                solution = solution.RemoveProject(project.Id);
+            }
+
+            if (kept is not null)
+            {
+                solution = solution.WithProjectName(kept.Id, ProjectFilters.StripTargetFramework(kept.Name));
+            }
+        }
+
+        return solution;
+    }
+
+    private static string? FindSolutionFile(string repoRoot)
+    {
+        // Top-level only: a nested solution usually belongs to a sample or a vendored dependency.
+        var candidates = Directory.EnumerateFiles(repoRoot, "*.slnx")
+            .Concat(Directory.EnumerateFiles(repoRoot, "*.sln"))
+            .Order(StringComparer.Ordinal)
+            .ToList();
+
+        return candidates.Count switch
+        {
+            0 => null,
+            1 => candidates[0],
+            _ => throw new WorkspaceLoadException(
+                $"More than one solution in {repoRoot}: {string.Join(", ", candidates.Select(Path.GetFileName))}"),
+        };
+    }
+
+    /// <summary>C# project files under <c>src/</c>, or under the repo root minus build output and dot folders.</summary>
+    private static (List<string> Files, string Glob) FindProjectFiles(string repoRoot)
+    {
+        var src = Path.Combine(repoRoot, "src");
+        var (searchRoot, glob) = Directory.Exists(src) ? (src, "src/**/*.csproj") : (repoRoot, "**/*.csproj");
+        var files = Directory
+            .EnumerateFiles(searchRoot, "*.csproj", SearchOption.AllDirectories)
+            .Where(file => !Path.GetRelativePath(repoRoot, file)
+                .Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar)
+                .Any(segment => segment is "bin" or "obj" || segment.StartsWith('.')))
+            .Where(file => !ProjectFilters.IsTestProject(Path.GetRelativePath(repoRoot, file), File.ReadAllText(file)))
+            .Order(StringComparer.Ordinal)
+            .ToList();
+        return (files, glob);
+    }
+
+    /// <summary>
+    /// MSBuildWorkspace needs restored projects (project.assets.json) to resolve references. Runs from the repo root
+    /// so the target's own global.json picks the SDK.
+    /// </summary>
+    private static async Task RestoreAsync(string path, string repoRoot)
+    {
+        var start = new ProcessStartInfo("dotnet", ["restore", path, "--nologo", "-v", "q"])
+        {
+            WorkingDirectory = repoRoot,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+        };
+        using var process = Process.Start(start)
+            ?? throw new WorkspaceLoadException("Could not start `dotnet restore`.");
+        var stdout = process.StandardOutput.ReadToEndAsync();
+        var stderr = process.StandardError.ReadToEndAsync();
+
+        using var timeout = new CancellationTokenSource(RestoreTimeout);
+        try
+        {
+            await process.WaitForExitAsync(timeout.Token);
+        }
+        catch (OperationCanceledException)
+        {
+            process.Kill(entireProcessTree: true);
+            throw new WorkspaceLoadException($"`dotnet restore {path}` did not finish within {RestoreTimeout.TotalMinutes} minutes.");
+        }
+
+        if (process.ExitCode != 0)
+        {
+            throw new WorkspaceLoadException(
+                $"`dotnet restore {path}` failed ({process.ExitCode}):{Environment.NewLine}{await stdout}{await stderr}");
+        }
+    }
+
+    private static bool PathsEqual(string? a, string b) =>
+        a is not null && string.Equals(Path.GetFullPath(a), Path.GetFullPath(b), StringComparison.OrdinalIgnoreCase);
+}

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

@@ -0,0 +1,41 @@
+namespace LogicalComponents.Tests;
+
+public class AssignIdsTests
+{
+    private static Component Unnamed(string type, string module) =>
+        new(Id: "", Type: type, Name: "", Module: module, Layer: "Application", Spans: []);
+
+    [Fact]
+    public void A_three_way_clash_across_modules_prefixes_every_member_with_its_module()
+    {
+        var named = ComponentDiscovery.AssignIds(
+        [
+            Unnamed("A.Export.Application.Reporting", "Export"),
+            Unnamed("A.Import.Application.Reporting", "Import"),
+            Unnamed("A.Jobs.Reporting", "BuildingBlocks"),
+            Unnamed("A.Export.Application.Framing", "Export"),
+        ]);
+
+        Assert.Equal(
+            [
+                ("A.Export.Application.Framing", "Framing", "Framing"),
+                ("A.Export.Application.Reporting", "Export_Reporting", "Reporting (Export)"),
+                ("A.Import.Application.Reporting", "Import_Reporting", "Reporting (Import)"),
+                ("A.Jobs.Reporting", "BuildingBlocks_Reporting", "Reporting (BuildingBlocks)"),
+            ],
+            named.Select(c => (c.Type, c.Id, c.Name)));
+    }
+
+    [Fact]
+    public void The_same_type_twice_is_an_error_rather_than_two_identical_ids()
+    {
+        // A source file linked into two projects declares the same full type name in both.
+        var error = Assert.Throws<InvalidOperationException>(() => ComponentDiscovery.AssignIds(
+        [
+            Unnamed("A.Shared.Clock", "Export"),
+            Unnamed("A.Shared.Clock", "Import"),
+        ]));
+
+        Assert.Contains("A.Shared.Clock", error.Message);
+    }
+}

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

@@ -0,0 +1,82 @@
+namespace LogicalComponents.Tests;
+
+public class BatchPlanningTests
+{
+    private static ExtractResult WithComponents(int count) => RenderTestData.Extraction with
+    {
+        Components = [.. Enumerable.Range(1, count).Select(i =>
+            new Component($"C{i:D3}", $"A.C{i:D3}", $"C {i:D3}", "A", "Application", [new SourceSpan($"src/C{i:D3}.cs", 1, 9)]))],
+        ExternalNodes = [],
+        Edges = [],
+    };
+
+    [Theory]
+    [InlineData(82, 9, new[] { 10, 10, 10, 10, 10, 10, 10, 10, 2 })]
+    [InlineData(20, 9, new[] { 3, 3, 3, 3, 3, 3, 2 })]
+    [InlineData(5, 9, new[] { 1, 1, 1, 1, 1 })]
+    public void Components_are_split_into_at_most_the_agent_count_of_equal_batches_in_extraction_order(
+        int components, int agents, int[] sizes)
+    {
+        var batches = BatchPlanning.Plan(WithComponents(components), agents);
+
+        Assert.Equal(sizes, batches.Select(b => b.Components.Count));
+        Assert.Equal(Enumerable.Range(1, sizes.Length), batches.Select(b => b.Batch));
+        Assert.Equal(
+            WithComponents(components).Components.Select(c => c.Id),
+            batches.SelectMany(b => b.Components).Select(c => c.Id));
+    }
+
+    [Fact]
+    public void Each_component_carries_its_spans_and_what_it_uses_by_name()
+    {
+        var batch = BatchPlanning.Plan(RenderTestData.Extraction, 9)
+            .SelectMany(b => b.Components)
+            .Single(c => c.Id == "OrderAcceptance");
+
+        Assert.Equal([new SourceSpan("src/App/OrderAcceptance.cs", 4, 17)], batch.Spans);
+        // Records compare their list members by reference, so compare the contents.
+        Assert.Equal(
+            [
+                ("IAuditTrail", "I Audit Trail", "di", ""),
+                ("OrderQueue", "Order Queue", "di,new", "IOrderQueue,IQueue"),
+            ],
+            batch.Uses.Select(u => (u.Id, u.Name, string.Join(",", u.Kinds), string.Join(",", u.Via))));
+    }
+
+    [Fact]
+    public void Each_component_carries_the_helper_code_it_runs()
+    {
+        var reaches = new List<SourceSpan> { new("src/Infra/OrderQueue.cs", 10, 10) };
+        var extraction = RenderTestData.Extraction with
+        {
+            Components = [RenderTestData.Extraction.Components[0] with { Reaches = reaches }, .. RenderTestData.Extraction.Components.Skip(1)],
+        };
+
+        var batch = BatchPlanning.Plan(extraction, 9).SelectMany(b => b.Components).Single(c => c.Id == "OrderAcceptance");
+
+        Assert.Equal(reaches, batch.Reaches);
+    }
+
+    [Fact]
+    public void Batch_files_are_written_identically_every_time()
+    {
+        var first = Directory.CreateTempSubdirectory("lc-batches-");
+        var second = Directory.CreateTempSubdirectory("lc-batches-");
+        try
+        {
+            BatchPlanning.Write(BatchPlanning.Plan(WithComponents(20), 9), first.FullName);
+            BatchPlanning.Write(BatchPlanning.Plan(WithComponents(20), 9), second.FullName);
+
+            var names = Directory.GetFiles(first.FullName).Select(Path.GetFileName).Order().ToList();
+            Assert.Equal(Enumerable.Range(1, 7).Select(i => $"batch-{i:D2}.json"), names);
+            Assert.All(names, n => Assert.Equal(
+                File.ReadAllBytes(Path.Combine(first.FullName, n!)),
+                File.ReadAllBytes(Path.Combine(second.FullName, n!))));
+        }
+        finally
+        {
+            first.Delete(recursive: true);
+            second.Delete(recursive: true);
+        }
+    }
+}

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

@@ -0,0 +1,34 @@
+namespace LogicalComponents.Tests;
+
+[Collection(FixtureSolutions.Name)]
+public class CandidatesCommandTests(SampleAppWorkspace sample)
+{
+    private static readonly ExtractConfig FixtureConfig = ExtractConfig.Load(FixturePaths.SampleApp);
+
+    [Fact]
+    public async Task Each_candidate_carries_its_spans_and_how_the_config_classifies_it()
+    {
+        var config = FixtureConfig with { Components = FixtureConfig.Components.Where(c => c != "Sample.Infrastructure.Mailer").ToList() };
+
+        var file = await CandidatesCommand.ListAsync(sample.Loaded, config, TestContext.Current.CancellationToken);
+        var byType = file.Candidates.ToDictionary(c => c.Type);
+
+        var acceptance = byType["Sample.Application.OrderAcceptance"];
+        Assert.Equal(("Application", "Sample", "component"), (acceptance.Layer, acceptance.Module, acceptance.Status));
+        Assert.Equal([new SourceSpan("src/Sample.Application/OrderAcceptance.cs", 4, 17)], acceptance.Spans);
+        Assert.Equal("helper", byType["Sample.Application.OrderNumber"].Status);
+        Assert.Equal("unclassified", byType["Sample.Infrastructure.Mailer"].Status);
+        Assert.Equal(file.Candidates.OrderBy(c => c.Type, StringComparer.Ordinal).Select(c => c.Type), file.Candidates.Select(c => c.Type));
+    }
+
+    [Fact]
+    public async Task Extract_refuses_unclassified_candidates_naming_each_one()
+    {
+        var config = FixtureConfig with { Components = FixtureConfig.Components.Where(c => c != "Sample.Infrastructure.Mailer").ToList() };
+
+        var error = await Assert.ThrowsAsync<UnclassifiedCandidatesException>(() =>
+            CouplingResolver.ExtractAsync(sample.Loaded, config, TestContext.Current.CancellationToken));
+
+        Assert.Equal(["Sample.Infrastructure.Mailer"], error.Types);
+    }
+}