@phuc1403/musketeer 0.10.0 → 0.12.0

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

@@ -0,0 +1,219 @@
+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, a citation inside the candidate's declaration, and a
+/// type the config does not already classify (a stale candidates.json could otherwise resend an already-reviewed type).
+/// 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 or a batch file 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);
+
+    /// <summary>A batch file from classify-batches could not be read: an environment/tooling problem, not the agents' fault.</summary>
+    private sealed class MalformedBatchException(string message) : Exception(message);
+
+    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");
+        }
+
+        List<VerdictJson> verdicts;
+        try
+        {
+            verdicts = Check(batchDir, verdictDir, existing, problems);
+        }
+        catch (MalformedBatchException e)
+        {
+            await output.WriteLineAsync(e.Message);
+            return 2;
+        }
+
+        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>
+    /// <exception cref="MalformedBatchException">A batch file itself (written by classify-batches, not an agent) is not valid JSON.</exception>
+    private static List<VerdictJson> Check(string batchDir, string verdictDir, ExtractConfig existing, 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)
+        {
+            ClassifyBatchesCommand.ClassifyBatch batch;
+            try
+            {
+                batch = ComponentsFile.FromJson<ClassifyBatchesCommand.ClassifyBatch>(File.ReadAllBytes(Path.Combine(batchDir, name)));
+            }
+            catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+            {
+                throw new MalformedBatchException($"{name}: not a valid batch file ({e.Message})");
+            }
+
+            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, existing) 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, ExtractConfig existing)
+    {
+        // Never overwrite a reviewed entry: a stale candidates.json could otherwise resend an already-classified type
+        // and have its verdict silently replace the reviewed reason, or put the type in both lists.
+        if (existing.IsClassified(candidate.Type))
+        {
+            return $"already classified in {ExtractConfig.FileName}; re-run candidates";
+        }
+
+        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 or hide a bidi/zero-width character in what looks like a normal sentence.
+        if (PlainText.HasDisallowedUnicode(verdict.Reason))
+        {
+            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 => PlainText.IsDisallowed(c) ? '?' : c).ToArray());
+}

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

@@ -0,0 +1,180 @@
+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 types = await SourceTypesAsync(loaded.Solution, cancellationToken);
+        if (types.All(t => t.Layer is not (ApplicationLayer or InfrastructureLayer)))
+        {
+            // Nothing to classify is easy to miss: an empty document with no explanation looks like success.
+            warnings.Add(
+                $"no {ApplicationLayer} or {InfrastructureLayer} project found among: {string.Join(", ", loaded.ProjectNames)}");
+        }
+
+        var candidates = types
+            .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);
+    /// a bare <c>Application</c>/<c>Infrastructure</c> project → that layer, itself as its module; matched
+    /// case-insensitively, so <c>Foo.application</c> counts too. 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 (string.Equals(projectName, layer, StringComparison.OrdinalIgnoreCase))
+            {
+                return (layer, projectName);
+            }
+
+            if (projectName.EndsWith("." + layer, StringComparison.OrdinalIgnoreCase))
+            {
+                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 — a source
+    /// generator's virtual document, or a real file under bin/ or 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,130 @@
+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
+{
+    // Host/DI builder types a composition root wires up. Matched by qualified name, not by referencing the host
+    // packages, since a target repo may use only some of them (a library-only Infrastructure project has no
+    // WebApplicationBuilder, for instance).
+    private static readonly string[] HostBuilderTypes =
+    [
+        "Microsoft.Extensions.DependencyInjection.IServiceCollection",
+        "Microsoft.Extensions.Hosting.IHostApplicationBuilder",
+        "Microsoft.AspNetCore.Builder.WebApplicationBuilder",
+        "Microsoft.Extensions.Hosting.IHostBuilder",
+    ];
+
+    private const string AutofacModule = "Autofac.Module";
+
+    /// <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> or a host builder (classic <c>this</c> parameter or a
+    /// C# 14 <c>extension(...)</c> block), or an Autofac <c>Module</c> overriding <c>Load</c>, wires the app together
+    /// and <c>new</c>s or reaches 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 && IsHostBuilderType(m.Parameters[0].Type))
+                || ExtensionBlocks(type).Any(block =>
+                    block.ExtensionParameter is { } parameter && IsHostBuilderType(parameter.Type))))
+        || IsAutofacModule(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
+    /// of its own. Not behaviour: constructors, accessors, operators, abstract methods, compiler-synthesized record
+    /// members, overrides of <c>object.ToString/Equals/GetHashCode</c> (formatting or comparing what the type holds),
+    /// and <c>extern</c>/<c>[DllImport]</c>/<c>[LibraryImport]</c> methods (no body of their own; the behaviour, if any,
+    /// is native code).
+    /// </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)
+                && !IsNativeInterop(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;
+    }
+
+    /// <summary>
+    /// A classic <c>extern</c> P/Invoke method, or a <c>[LibraryImport]</c> partial method: the attribute lives on the
+    /// partial definition part, not the source-generator-written implementation part, so both parts are checked.
+    /// </summary>
+    private static bool IsNativeInterop(IMethodSymbol method)
+    {
+        var definition = method.PartialDefinitionPart ?? method;
+        return definition.IsExtern
+            || definition.GetAttributes().Any(a => a.AttributeClass is { } attribute
+                && SymbolNames.QualifiedName(attribute) is
+                    "System.Runtime.InteropServices.DllImportAttribute" or "System.Runtime.InteropServices.LibraryImportAttribute");
+    }
+
+    private static IEnumerable<INamedTypeSymbol> ExtensionBlocks(INamedTypeSymbol type) =>
+        type.GetTypeMembers().Where(t => t.IsExtension);
+
+    private static bool IsHostBuilderType(ITypeSymbol type) => HostBuilderTypes.Contains(SymbolNames.QualifiedName(type));
+
+    // Autofac.Module declares Load as virtual (empty by default); matching by name keeps this working without
+    // referencing Autofac.
+    private static bool IsAutofacModule(INamedTypeSymbol type)
+    {
+        for (var current = type.BaseType; current is not null; current = current.BaseType)
+        {
+            if (SymbolNames.QualifiedName(current) == AutofacModule)
+            {
+                return type.GetMembers("Load").OfType<IMethodSymbol>().Any(m => m.IsOverride);
+            }
+        }
+
+        return false;
+    }
+}

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

@@ -0,0 +1,101 @@
+using System.Security.Cryptography;
+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.
+/// <see cref="FileHashes"/> is a repo-relative-file → content-hash map covering every file any component span, reach or
+/// edge citation points into, so <c>render</c> can tell whether the repo changed since extraction. Null when read from
+/// a components.json written before this map existed.
+/// </summary>
+public sealed record ExtractResult(
+    IReadOnlyList<Component> Components,
+    IReadOnlyList<ExternalNode> ExternalNodes,
+    IReadOnlyList<Edge> Edges,
+    IReadOnlyList<string> Warnings,
+    IReadOnlyDictionary<string, string>? FileHashes = null);
+
+/// <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,
+            fileHashes = result.FileHashes,
+        });
+
+    /// <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");
+
+    /// <summary>
+    /// SHA-256 of a repo file's text, lowercase hex, with CRLF normalized to LF first so a checkout's line-ending
+    /// setting never changes the hash.
+    /// </summary>
+    public static string HashFile(string path) => HashText(File.ReadAllText(path));
+
+    /// <summary>SHA-256 of text with CRLF normalized to LF, as lowercase hex.</summary>
+    public static string HashText(string text) =>
+        Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(text.Replace("\r\n", "\n"))));
+}