@phuc1403/musketeer 0.10.0 → 0.11.0

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);
+}

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());
+}