@phuc1403/musketeer 0.10.0 → 0.12.0

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

@@ -0,0 +1,251 @@
+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);
+            var baseBindings = new List<(ITypeParameterSymbol Parameter, ITypeSymbol Argument)>();
+
+            // 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. Roslyn
+            // resolves BaseType through the whole construction chain, so a generic base's own type parameters bind to
+            // what this component (or an intermediate base) actually supplies, however many levels deep.
+            for (var constructedBase = symbol.BaseType;
+                 constructedBase is not null && CitableSource.IsRepoSource(constructedBase.OriginalDefinition, loaded);
+                 constructedBase = constructedBase.BaseType)
+            {
+                var baseType = constructedBase.OriginalDefinition;
+                var baseName = SymbolNames.FullName(baseType);
+                if (components.Contains(baseName))
+                {
+                    var (file, line) = await BaseListLocationAsync(declarations, baseType, loaded, cancellationToken)
+                        ?? (component.Spans[0].File, component.Spans[0].Start);
+                    raw.Add(new(component.Type, baseName, EdgeExtraction.Inherits, [], file, line));
+                    break;
+                }
+
+                self.Add(baseName);
+                baseBindings.AddRange(TypeMap.Zip(baseType.TypeParameters, constructedBase.TypeArguments));
+                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, TypeMap.FromBindings(baseBindings), cancellationToken);
+            raw.AddRange(resolved.Edges);
+            reaches[component.Type] = resolved.Reaches;
+            warnings.AddRange(resolved.Warnings);
+        }
+
+        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)];
+        }
+
+        var via = SymbolNames.FullName(target.OriginalDefinition);
+        return implementations
+            .Select(SymbolNames.FullName)
+            .Where(components.Contains)
+            .Select(to => new MemberUseResolution.RawEdge(from, to, EdgeExtraction.Di, [via], reference.File, reference.Line))
+            .ToList();
+    }
+
+    /// <summary>
+    /// Where a partial class names <paramref name="baseType"/> as its base: the base list of the declaration whose base
+    /// list actually contains it, not merely the first declaration that has any base list (a partial fragment can list
+    /// only interfaces). Ties (there should be at most one match; a duplicate base is a compile error) break by file
+    /// path ordinal, then position.
+    /// </summary>
+    private static async Task<(string File, int Line)?> BaseListLocationAsync(
+        IEnumerable<SyntaxNode> declarations, INamedTypeSymbol baseType, LoadedWorkspace loaded, CancellationToken cancellationToken)
+    {
+        var matches = new List<(string File, int Line)>();
+        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 || loaded.Solution.GetDocument(baseList.SyntaxTree) is not { } document)
+            {
+                continue;
+            }
+
+            var model = await document.GetSemanticModelAsync(cancellationToken)
+                ?? throw new InvalidOperationException($"No semantic model for {file}");
+            var namesBaseType = baseList.Types.Any(t =>
+                model.GetSymbolInfo(t.Type, cancellationToken).Symbol is INamedTypeSymbol candidate
+                && SymbolEqualityComparer.Default.Equals(candidate.OriginalDefinition, baseType));
+            if (namesBaseType)
+            {
+                matches.Add((file, baseList.GetLocation().GetLineSpan().StartLinePosition.Line + 1));
+            }
+        }
+
+        return matches.Count == 0 ? null : matches.OrderBy(m => m.File, StringComparer.Ordinal).ThenBy(m => m.Line).First();
+    }
+
+    /// <summary>
+    /// CS1705: a referenced assembly was built against a newer framework. The loader keeps one target framework per
+    /// multi-targeted project, so a project on an older framework that references it always gets this error, yet every
+    /// symbol still binds. It says nothing about missing edges.
+    /// </summary>
+    private const string NewerFrameworkReference = "CS1705";
+
+    /// <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 && d.Id != NewerFrameworkReference) ?? 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 as a sorted set, cited at the earliest (file, line) recorded use, with <c>via</c>
+    /// naming the seams and seen-through types on that earliest use's own path (the first path found), in the order the
+    /// walk actually followed it rather than merged and alphabetised across every raw edge to the same target.
+    /// </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(),
+                    DisambiguatedVia(first.Via),
+                    $"{first.File}:{first.Line}");
+            })
+            .OrderBy(e => e.From, StringComparer.Ordinal)
+            .ThenBy(e => e.To, StringComparer.Ordinal)
+            .ToList();
+
+    /// <summary>
+    /// <paramref name="via"/> holds each step's full metadata name (stable identity). Displayed as its plain simple
+    /// name, except when a simple name on the path is shared by two genuinely different full names (two unrelated
+    /// <c>Builder</c>s): every step with that simple name then falls back to its readable full name instead of
+    /// collapsing into one indistinguishable entry. A single type revisited twice on the same path (it is not its own
+    /// collision) still displays by its plain simple name both times.
+    /// </summary>
+    private static List<string> DisambiguatedVia(IReadOnlyList<string> via)
+    {
+        var colliding = via.GroupBy(SymbolNames.SimpleName)
+            .Where(g => g.Distinct(StringComparer.Ordinal).Count() > 1)
+            .Select(g => g.Key)
+            .ToHashSet(StringComparer.Ordinal);
+        return via
+            .Select(name => colliding.Contains(SymbolNames.SimpleName(name)) ? SymbolNames.ReadableFullName(name) : SymbolNames.SimpleName(name))
+            .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,87 @@
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>extract &lt;repoPath&gt; [--out &lt;components.json&gt;] [--solution &lt;file&gt;]</c>: loads the repo and writes the
+/// deterministic extraction, including a hash of every cited file's content (see <see cref="FileHashes"/>) so
+/// <c>render</c> can tell whether the repo changed since. <c>--solution</c> picks the solution file as in
+/// <c>candidates</c>. 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>] [--solution <file>]";
+
+    public static async Task<int> RunAsync(string[] args, TextWriter errors)
+    {
+        if (args is not [var repoPath, ..]
+            || !CandidatesCommand.TryParseOptions(args[1..], "components.json", out var outPath, out var solution))
+        {
+            await errors.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        try
+        {
+            using var loaded = await WorkspaceLoader.LoadAsync(repoPath, solution: solution, log: errors);
+            await errors.WriteLineAsync($"Loaded {loaded.ProjectNames.Count} projects from {loaded.Source}.");
+
+            var extracted = await CouplingResolver.ExtractAsync(loaded, ExtractConfig.Load(loaded.RepoRoot));
+            var result = extracted with { FileHashes = FileHashes(loaded.RepoRoot, extracted) };
+            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;
+        }
+    }
+
+    /// <summary>
+    /// A repo-relative-file → content-hash map (see <see cref="ComponentsFile.HashFile"/>) for every file any component's
+    /// spans, reaches or outgoing edge citations point into, so <c>render</c> can later tell whether the repo changed.
+    /// </summary>
+    private static IReadOnlyDictionary<string, string> FileHashes(string repoRoot, ExtractResult result)
+    {
+        var files = result.Components
+            .SelectMany(c => c.Spans.Concat(c.Reaches ?? []).Select(s => s.File))
+            .Concat(result.Edges.Select(e => Citation.Parse(e.At)?.File).OfType<string>())
+            .Distinct(StringComparer.Ordinal)
+            .Order(StringComparer.Ordinal);
+
+        var hashes = new SortedDictionary<string, string>(StringComparer.Ordinal);
+        foreach (var file in files)
+        {
+            hashes[file] = ComponentsFile.HashFile(Path.Combine(repoRoot, file));
+        }
+
+        return hashes;
+    }
+}

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/MarkdownCodeSpans.cs

@@ -0,0 +1,72 @@
+using System.Text;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// CommonMark code-span parsing for <see cref="ResponsibilityValidation"/>'s plain-text check: a backtick run of
+/// length n opens a code span, which closes at the next run of exactly length n (a run of a different length inside is
+/// literal content; a run with no matching close is an unclosed delimiter, not a span). A naive `` `[^`]*` `` match
+/// gets this wrong for an escaped or mismatched backtick, which could let HTML or a link hide inside what looks like,
+/// but is not, a real code span.
+/// </summary>
+public static class MarkdownCodeSpans
+{
+    /// <summary>The text with every real code span removed, and whether any backtick run was left unmatched.</summary>
+    public static (string Outside, bool Unclosed) Strip(string text)
+    {
+        var outside = new StringBuilder();
+        var unclosed = false;
+        var i = 0;
+        while (i < text.Length)
+        {
+            if (text[i] != '`')
+            {
+                outside.Append(text[i]);
+                i++;
+                continue;
+            }
+
+            var openStart = i;
+            while (i < text.Length && text[i] == '`')
+            {
+                i++;
+            }
+
+            var openLength = i - openStart;
+            var closeStart = -1;
+            var j = i;
+            while (j < text.Length)
+            {
+                if (text[j] != '`')
+                {
+                    j++;
+                    continue;
+                }
+
+                var runStart = j;
+                while (j < text.Length && text[j] == '`')
+                {
+                    j++;
+                }
+
+                if (j - runStart == openLength)
+                {
+                    closeStart = runStart;
+                    break;
+                }
+            }
+
+            if (closeStart >= 0)
+            {
+                i = closeStart + openLength;
+            }
+            else
+            {
+                unclosed = true;
+                outside.Append('`', openLength);
+            }
+        }
+
+        return (outside.ToString(), unclosed);
+    }
+}