@phuc1403/musketeer 0.10.0 → 0.11.0

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

@@ -0,0 +1,37 @@
+using System.Text.RegularExpressions;
+
+namespace LogicalComponents;
+
+/// <summary>One responsibility an agent wrote for a component, and the source lines it claims show it.</summary>
+public sealed record Responsibility(string Text, string Cite);
+
+/// <summary>
+/// A parsed <c>file:line</c> or <c>file:start-end</c> citation: a repo-relative path with forward slashes and a 1-based,
+/// inclusive line range. Anything looser (surrounding whitespace, control characters, backslashes, non-ASCII digits,
+/// absurd line numbers) does not parse, so it can never reach the rendered document.
+/// </summary>
+public sealed partial record Citation(string File, int Start, int End)
+{
+    public int LineCount => End - Start + 1;
+
+    public static Citation? Parse(string cite)
+    {
+        var match = Pattern().Match(cite);
+        if (!match.Success)
+        {
+            return null;
+        }
+
+        var start = int.Parse(match.Groups["start"].Value);
+        var end = match.Groups["end"].Success ? int.Parse(match.Groups["end"].Value) : start;
+        return start >= 1 && end >= start ? new Citation(match.Groups["file"].Value, start, end) : null;
+    }
+
+    /// <summary>The canonical form rendered in the document: <c>file:7</c> or <c>file:7-12</c>, never <c>file:0007-007</c>.</summary>
+    public override string ToString() => Start == End ? $"{File}:{Start}" : $"{File}:{Start}-{End}";
+
+    // At most 7 ASCII digits per number, so int.Parse cannot overflow; \z (not $) so a trailing newline cannot slip
+    // through; the path has no colon, backslash or control character and neither starts nor ends with whitespace.
+    [GeneratedRegex(@"\A(?<file>[^:\\\s\p{C}](?:[^:\\\p{C}]*[^:\\\s\p{C}])?):(?<start>[0-9]{1,7})(?:-(?<end>[0-9]{1,7}))?\z")]
+    private static partial Regex Pattern();
+}

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

@@ -0,0 +1,65 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>classify-batches --candidates &lt;candidates.json&gt; --agents &lt;n&gt; --repo &lt;repoPath&gt; --out &lt;dir&gt;</c>: splits
+/// the candidates the config does not classify yet into at most n equal batches, in candidates.json order, one
+/// <c>batch-NN.json</c> per classifier agent. Already classified candidates are never sent again. It also records the
+/// repo config's hash, so classify-merge can refuse to merge if anything edited the config in between.
+/// Exit codes: 0 written, 1 usage, 2 unreadable candidates.json.
+/// </summary>
+public static class ClassifyBatchesCommand
+{
+    public const string Usage =
+        "usage: LogicalComponents classify-batches --candidates <candidates.json> --agents <n> --repo <repoPath> --out <dir>";
+
+    /// <summary>The file in the batches directory holding the config hash at batching time.</summary>
+    public const string ConfigHashFile = "config.sha256";
+
+    public sealed record ClassifyCandidate(string Type, string Layer, string Module, IReadOnlyList<SourceSpan> Spans);
+
+    public sealed record ClassifyBatch(int Batch, IReadOnlyList<ClassifyCandidate> Candidates);
+
+    public static async Task<int> RunAsync(string[] args, TextWriter output)
+    {
+        if (args is not ["--candidates", var candidatesPath, "--agents", var agentsText, "--repo", var repo, "--out", var outDir]
+            || !int.TryParse(agentsText, out var agents) || agents < 1 || !Directory.Exists(repo))
+        {
+            await output.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        CandidatesCommand.CandidatesFile file;
+        try
+        {
+            file = ComponentsFile.FromJson<CandidatesCommand.CandidatesFile>(await File.ReadAllBytesAsync(candidatesPath));
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+        {
+            await output.WriteLineAsync($"Cannot read {candidatesPath}: {e.Message}");
+            return 2;
+        }
+
+        var unclassified = file.Candidates
+            .Where(c => c.Status == CandidatesCommand.Unclassified)
+            .Select(c => new ClassifyCandidate(c.Type, c.Layer, c.Module, c.Spans))
+            .ToList();
+        var size = Math.Max(1, (unclassified.Count + agents - 1) / agents);
+        var batches = unclassified.Chunk(size).Select((chunk, index) => new ClassifyBatch(index + 1, chunk)).ToList();
+
+        BatchPlanning.Write(batches, b => b.Batch, outDir);
+        await File.WriteAllTextAsync(Path.Combine(outDir, ConfigHashFile), ConfigHash(repo));
+        await output.WriteLineAsync(
+            $"{unclassified.Count} unclassified candidates in {batches.Count} batches -> {Path.GetFullPath(outDir)}");
+        return 0;
+    }
+
+    /// <summary>SHA-256 of the repo's config file as it is now, or <c>absent</c>.</summary>
+    public static string ConfigHash(string repo)
+    {
+        var path = Path.Combine(repo, ExtractConfig.FileName);
+        return File.Exists(path) ? Convert.ToHexString(SHA256.HashData(File.ReadAllBytes(path))) : "absent";
+    }
+}

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

@@ -0,0 +1,187 @@
+using System.Text.Json;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>classify-merge --batches &lt;dir&gt; --verdicts &lt;dir&gt; --repo &lt;repoPath&gt;</c>: adds the classifier agents' verdicts
+/// (<c>verdicts/batch-NN.json</c>: <c>[{ type, verdict: component|helper, reason, cite }]</c>) to the repo's
+/// <c>logical-components.json</c>. The agents' output is checked against the batches they were given before anything is
+/// written: one verdict file per batch and none left over, exactly one verdict per candidate of the batch and no other
+/// type, a known verdict, a one-line reason under 200 characters, and a citation inside the candidate's declaration.
+/// The config must be unchanged since classify-batches, so nothing can slip an entry past the review.
+/// Prints each added entry (helpers first, for review) and a summary on <c>output</c>.
+/// Exit codes: 0 written, 1 usage, 2 the existing config is unreadable, 3 the verdicts break the contract or the config
+/// changed (every problem listed, nothing written).
+/// </summary>
+public static class ClassifyMergeCommand
+{
+    public const string Usage = "usage: LogicalComponents classify-merge --batches <dir> --verdicts <dir> --repo <repoPath>";
+
+    private const int MaxReasonLength = 200;
+    private const int MaxCitedLines = 30;
+
+    private sealed record VerdictJson(string? Type, string? Verdict, string? Reason, string? Cite);
+
+    public static async Task<int> RunAsync(string[] args, TextWriter output)
+    {
+        if (args is not ["--batches", var batchDir, "--verdicts", var verdictDir, "--repo", var repo]
+            || !Directory.Exists(batchDir) || !Directory.Exists(verdictDir) || !Directory.Exists(repo))
+        {
+            await output.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        ExtractConfig existing;
+        try
+        {
+            existing = ExtractConfig.Load(repo);
+        }
+        catch (ExtractConfigException e)
+        {
+            await output.WriteLineAsync(e.Message);
+            return 2;
+        }
+
+        var problems = new List<string>();
+        var hashFile = Path.Combine(batchDir, ClassifyBatchesCommand.ConfigHashFile);
+        if (!File.Exists(hashFile) || File.ReadAllText(hashFile) != ClassifyBatchesCommand.ConfigHash(repo))
+        {
+            problems.Add($"{ExtractConfig.FileName} changed since classify-batches; review that change, then batch again");
+        }
+
+        var verdicts = Check(batchDir, verdictDir, problems);
+        if (problems.Count > 0)
+        {
+            foreach (var problem in problems)
+            {
+                await output.WriteLineAsync(problem);
+            }
+
+            return 3;
+        }
+
+        var components = existing.Components.ToHashSet(StringComparer.Ordinal);
+        var helpers = new SortedDictionary<string, string>(existing.Helpers.ToDictionary(), StringComparer.Ordinal);
+        var added = verdicts.OrderBy(v => v.Type, StringComparer.Ordinal).ToList();
+        foreach (var verdict in added)
+        {
+            if (verdict.Verdict == CandidatesCommand.Helper)
+            {
+                helpers[verdict.Type!] = verdict.Reason!;
+            }
+            else
+            {
+                components.Add(verdict.Type!);
+            }
+        }
+
+        if (added.Count > 0)
+        {
+            await File.WriteAllBytesAsync(
+                Path.Combine(repo, ExtractConfig.FileName),
+                ComponentsFile.ToJson(new { components = components.Order(StringComparer.Ordinal), helpers }));
+        }
+
+        foreach (var verdict in added.OrderBy(v => v.Verdict == CandidatesCommand.Helper ? 0 : 1))
+        {
+            await output.WriteLineAsync($"{verdict.Verdict} {verdict.Type}: {verdict.Reason}");
+        }
+
+        await output.WriteLineAsync(
+            $"{added.Count(v => v.Verdict == CandidatesCommand.Component)} components, "
+            + $"{added.Count(v => v.Verdict == CandidatesCommand.Helper)} helpers added");
+        return 0;
+    }
+
+    /// <summary>Every verdict of every batch, or problems (in batch file order) when the agents' output breaks the contract.</summary>
+    private static List<VerdictJson> Check(string batchDir, string verdictDir, List<string> problems)
+    {
+        var batchFiles = Directory.EnumerateFiles(batchDir, "batch-*.json").Select(Path.GetFileName).OfType<string>()
+            .Order(StringComparer.Ordinal).ToList();
+        problems.AddRange(Directory.EnumerateFiles(verdictDir, "batch-*.json").Select(Path.GetFileName).OfType<string>()
+            .Where(name => !batchFiles.Contains(name))
+            .Order(StringComparer.Ordinal)
+            .Select(name => $"{name}: verdicts for a batch that does not exist (left from an earlier round?)"));
+
+        var all = new List<VerdictJson>();
+        foreach (var name in batchFiles)
+        {
+            var batch = ComponentsFile.FromJson<ClassifyBatchesCommand.ClassifyBatch>(File.ReadAllBytes(Path.Combine(batchDir, name)));
+            var verdictPath = Path.Combine(verdictDir, name);
+            if (!File.Exists(verdictPath))
+            {
+                problems.Add($"{name}: no verdict file");
+                continue;
+            }
+
+            List<VerdictJson?> read;
+            try
+            {
+                read = ComponentsFile.FromJson<List<VerdictJson?>>(File.ReadAllBytes(verdictPath));
+            }
+            catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+            {
+                problems.Add($"{name}: not a verdict array ({e.Message})");
+                continue;
+            }
+
+            var verdicts = read.OfType<VerdictJson>().ToList();
+            var candidates = batch.Candidates.ToDictionary(c => c.Type, StringComparer.Ordinal);
+            foreach (var group in verdicts.GroupBy(v => v.Type ?? "", StringComparer.Ordinal))
+            {
+                if (!candidates.TryGetValue(group.Key, out var candidate))
+                {
+                    problems.Add($"{name}: {Printable(group.Key)}: not a candidate of this batch");
+                }
+                else if (group.Count() > 1)
+                {
+                    problems.Add($"{name}: {group.Key}: more than one verdict");
+                }
+                else if (Problem(group.Single(), candidate) is { } problem)
+                {
+                    problems.Add($"{name}: {group.Key}: {problem}");
+                }
+            }
+
+            problems.AddRange(candidates.Keys.Where(type => verdicts.All(v => v.Type != type))
+                .Select(type => $"{name}: {type}: no verdict"));
+            all.AddRange(verdicts);
+        }
+
+        return all;
+    }
+
+    private static string? Problem(VerdictJson verdict, ClassifyBatchesCommand.ClassifyCandidate candidate)
+    {
+        if (verdict.Verdict is not (CandidatesCommand.Component or CandidatesCommand.Helper))
+        {
+            return "verdict must be component or helper";
+        }
+
+        if (string.IsNullOrWhiteSpace(verdict.Reason))
+        {
+            return "reason is empty";
+        }
+
+        // The reason is printed at the review gate and stored in the config: one plain line, so it cannot fake other lines.
+        if (verdict.Reason.Any(char.IsControl))
+        {
+            return "reason has control characters";
+        }
+
+        if (verdict.Reason.Length > MaxReasonLength)
+        {
+            return $"reason is {verdict.Reason.Length} characters; keep it under {MaxReasonLength}";
+        }
+
+        var cite = Citation.Parse(verdict.Cite ?? "");
+        return cite is not null
+            && cite.LineCount <= MaxCitedLines
+            && candidate.Spans.Any(s => s.File == cite.File && s.Start <= cite.Start && cite.End <= s.End)
+            ? null
+            : $"cite '{verdict.Cite}' is not inside its declaration";
+    }
+
+    // An unknown type is agent text: print it without anything that could start a new line at the review gate.
+    private static string Printable(string text) => new(text.Select(c => char.IsControl(c) ? '?' : c).ToArray());
+}

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

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

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

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

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

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