@phuc1403/musketeer 0.10.0 → 0.11.0

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

@@ -0,0 +1,173 @@
+using System.Text;
+using System.Text.Json;
+using Microsoft.CodeAnalysis.Text;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>render --components &lt;components.json&gt; --resp &lt;dir|file&gt;... --repo &lt;repoPath&gt; --out &lt;md&gt;</c>.
+/// Merges the agents' batch files (a directory means every <c>batch-*.json</c> in it, read in name order), validates them
+/// against the extraction and the repo's files, and writes the markdown only when everything is valid.
+/// Exit codes: 0 written; 1 usage; 2 inputs unusable (unreadable components.json, a missing path, a repo that does not
+/// match components.json, an unwritable --out); 3 responsibilities rejected, every problem on stderr and no --out left.
+/// </summary>
+public static class RenderCommand
+{
+    public const string Usage =
+        "usage: LogicalComponents render --components <components.json> --resp <dir|file>... --repo <repoPath> --out <md>";
+
+    private static readonly JsonSerializerOptions ReadOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+        // The same component twice in one file must not silently keep the last list.
+        AllowDuplicateProperties = false,
+    };
+
+    private sealed record Arguments(string Components, IReadOnlyList<string> Resp, string Repo, string Out);
+
+    public static async Task<int> RunAsync(string[] args, TextWriter errors)
+    {
+        var arguments = ParseArgs(args);
+        if (arguments is null)
+        {
+            await errors.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        var extraction = await ReadExtractionAsync(arguments.Components, errors);
+        if (extraction is null)
+        {
+            return 2;
+        }
+
+        var missing = arguments.Resp.Where(p => !Directory.Exists(p) && !File.Exists(p))
+            .Concat(Directory.Exists(arguments.Repo) ? [] : [arguments.Repo])
+            .ToList();
+        if (missing.Count > 0)
+        {
+            await errors.WriteLineAsync($"Not found: {string.Join(", ", missing)}");
+            return 2;
+        }
+
+        // Checked before any citation: a repo that does not match components.json is not the agents' fault.
+        var sourceLines = ReadSourceLines(extraction, arguments.Repo, out var missingSources);
+        if (missingSources.Count > 0)
+        {
+            await errors.WriteLineAsync(
+                $"The repo does not match components.json (re-run extract); missing: {string.Join(", ", missingSources)}");
+            return 2;
+        }
+
+        var batches = ResponsibilityBatches.Load(arguments.Resp, ReadOptions);
+        var problems = batches.Problems
+            .Concat(ResponsibilityValidation.Validate(extraction, batches.Responsibilities, sourceLines, batches.FileOf))
+            .ToList();
+        if (problems.Count > 0)
+        {
+            foreach (var problem in problems)
+            {
+                await errors.WriteLineAsync(problem);
+            }
+
+            // Never leave a document from an earlier run looking like this run's result.
+            if (File.Exists(arguments.Out))
+            {
+                File.Delete(arguments.Out);
+            }
+
+            return 3;
+        }
+
+        try
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(arguments.Out))!);
+            var markdown = MarkdownRenderer.Render(extraction, batches.Responsibilities);
+            await File.WriteAllBytesAsync(arguments.Out, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(markdown));
+            return 0;
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException)
+        {
+            await errors.WriteLineAsync($"Cannot write {arguments.Out}: {e.Message}");
+            return 2;
+        }
+    }
+
+    private static async Task<ExtractResult?> ReadExtractionAsync(string path, TextWriter errors)
+    {
+        try
+        {
+            var extraction = ComponentsFile.Deserialize(await File.ReadAllBytesAsync(path));
+            // Deserialization leaves absent lists null despite the non-nullable types: `{}` is not a components.json.
+            if (extraction.Components is not null && extraction.ExternalNodes is not null
+                && extraction.Edges is not null && extraction.Warnings is not null)
+            {
+                return extraction;
+            }
+
+            await errors.WriteLineAsync($"{path} is not a components.json written by extract");
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+        {
+            await errors.WriteLineAsync($"Cannot read {path}: {e.Message}");
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// The lines of every file a component is declared in, split the way Roslyn splits them (so U+2028 and friends count
+    /// exactly as they did when extract measured the spans). Files missing from the repo are reported, not read.
+    /// </summary>
+    private static Dictionary<string, IReadOnlyList<string>> ReadSourceLines(
+        ExtractResult extraction, string repo, out List<string> missing)
+    {
+        var lines = new Dictionary<string, IReadOnlyList<string>>(StringComparer.Ordinal);
+        missing = [];
+        var files = extraction.Components.SelectMany(c => c.Spans.Concat(c.Reaches ?? []).Select(s => s.File));
+        foreach (var file in files.Distinct().Order(StringComparer.Ordinal))
+        {
+            var path = Path.Combine(repo, file);
+            if (!File.Exists(path))
+            {
+                missing.Add(file);
+                continue;
+            }
+
+            var text = SourceText.From(File.ReadAllText(path));
+            lines[file] = text.Lines.Select(l => text.ToString(l.Span)).ToList();
+        }
+
+        return lines;
+    }
+
+    /// <summary>Each flag exactly once; <c>--resp</c> takes every following value up to the next flag.</summary>
+    private static Arguments? ParseArgs(string[] args)
+    {
+        var values = new Dictionary<string, List<string>>(StringComparer.Ordinal);
+        for (var i = 0; i < args.Length; i++)
+        {
+            var flag = args[i];
+            if (flag is not ("--components" or "--resp" or "--repo" or "--out") || values.ContainsKey(flag))
+            {
+                return null;
+            }
+
+            var taken = new List<string>();
+            while (i + 1 < args.Length && !args[i + 1].StartsWith("--", StringComparison.Ordinal))
+            {
+                taken.Add(args[++i]);
+            }
+
+            values[flag] = taken;
+        }
+
+        string? Single(string flag) => values.TryGetValue(flag, out var v) && v.Count == 1 ? v[0] : null;
+        var resp = values.GetValueOrDefault("--resp") ?? [];
+        return Single("--components") is { } components && Single("--repo") is { } repo && Single("--out") is { } output
+               && resp.Count > 0
+            ? new Arguments(components, resp, repo, output)
+            : null;
+    }
+}

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

@@ -0,0 +1,84 @@
+using System.Text.Json;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// The agents' batch files merged by component id, with every problem found while reading them. A component answered in
+/// two files keeps the first file's answer (so validation can still report everything else) and is a problem; a null
+/// list reads as no responsibilities; a null item is a problem naming its file.
+/// </summary>
+public sealed record ResponsibilityBatches(
+    Dictionary<string, IReadOnlyList<Responsibility>> Responsibilities,
+    Dictionary<string, string> FileOf,
+    List<string> Problems)
+{
+    /// <summary>A directory contributes its <c>batch-*.json</c> files in name order; any other path is read as a file.</summary>
+    public static ResponsibilityBatches Load(IEnumerable<string> paths, JsonSerializerOptions options)
+    {
+        var files = paths
+            .SelectMany(p => Directory.Exists(p)
+                ? Directory.EnumerateFiles(p, "batch-*.json").Order(StringComparer.Ordinal)
+                : (IEnumerable<string>)[p])
+            .ToList();
+        var batches = new ResponsibilityBatches(new(StringComparer.Ordinal), new(StringComparer.Ordinal), []);
+        var sources = new Dictionary<string, List<string>>(StringComparer.Ordinal);
+
+        foreach (var file in files)
+        {
+            var name = Path.GetFileName(file);
+            Dictionary<string, List<Responsibility?>?>? content;
+            try
+            {
+                content = JsonSerializer.Deserialize<Dictionary<string, List<Responsibility?>?>>(File.ReadAllText(file), options);
+            }
+            catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+            {
+                batches.Problems.Add($"{name}: not a valid responsibilities file ({e.Message})");
+                continue;
+            }
+
+            foreach (var (id, items) in content ?? [])
+            {
+                if (!sources.TryGetValue(id, out var seenIn))
+                {
+                    seenIn = [];
+                    sources[id] = seenIn;
+                }
+
+                seenIn.Add(name);
+                if (seenIn.Count > 1)
+                {
+                    continue;
+                }
+
+                batches.FileOf[id] = name;
+                batches.Responsibilities[id] = Clean(id, name, items ?? [], batches.Problems);
+            }
+        }
+
+        batches.Problems.AddRange(sources
+            .Where(s => s.Value.Count > 1)
+            .OrderBy(s => s.Key, StringComparer.Ordinal)
+            .Select(s => $"{s.Key}: responsibilities in more than one file ({string.Join(", ", s.Value)})"));
+        return batches;
+    }
+
+    // Null items become problems; null fields become empty strings so validation reports them as empty text or bad cites.
+    private static List<Responsibility> Clean(string id, string file, List<Responsibility?> items, List<string> problems)
+    {
+        var clean = new List<Responsibility>();
+        for (var index = 0; index < items.Count; index++)
+        {
+            if (items[index] is { } item)
+            {
+                clean.Add(new Responsibility(item.Text ?? "", item.Cite ?? ""));
+            }
+            else
+            {
+                problems.Add($"{id}[{index + 1}]: item is null ({file})");
+            }
+        }
+
+        return clean;
+    }
+}

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

@@ -0,0 +1,178 @@
+using System.Text.RegularExpressions;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Checks the agents' responsibilities against the deterministic extraction before anything is rendered. Agents may
+/// only describe the components extract found; every component needs at least one responsibility; each is one plain
+/// line of text, said once; and its citation must cover real code inside that component's own declaration. All problems
+/// are reported at once, sorted by component id then item, so a retry can fix everything in one pass.
+/// </summary>
+public static partial class ResponsibilityValidation
+{
+    public const int MaxCitedLines = 60;
+    public const int MaxTextLength = 300;
+
+    /// <param name="sourceLines">The lines of every file a component is declared in, keyed by repo-relative path.</param>
+    /// <param name="fileOf">Which batch file each responsibility id came from, to route unknown-id errors.</param>
+    public static List<string> Validate(
+        ExtractResult extraction,
+        IReadOnlyDictionary<string, IReadOnlyList<Responsibility>> responsibilities,
+        IReadOnlyDictionary<string, IReadOnlyList<string>> sourceLines,
+        IReadOnlyDictionary<string, string>? fileOf = null)
+    {
+        var errors = new List<(string Id, int Item, string Message)>();
+        var components = extraction.Components.ToDictionary(c => c.Id, StringComparer.Ordinal);
+
+        foreach (var id in responsibilities.Keys.Where(id => !components.ContainsKey(id)))
+        {
+            errors.Add((id, 0, UnknownId(id, components.Keys, fileOf)));
+        }
+
+        foreach (var component in extraction.Components)
+        {
+            if (!responsibilities.TryGetValue(component.Id, out var items) || items.Count == 0)
+            {
+                errors.Add((component.Id, 0, $"{component.Id}: no responsibilities"));
+                continue;
+            }
+
+            var seen = new Dictionary<string, int>(StringComparer.Ordinal);
+            for (var index = 0; index < items.Count; index++)
+            {
+                var item = index + 1;
+                var prefix = $"{component.Id}[{item}]: ";
+                if (TextProblem(items[index].Text) is { } textProblem)
+                {
+                    errors.Add((component.Id, item, prefix + textProblem));
+                }
+                else if (!seen.TryAdd(Normalize(items[index].Text), item))
+                {
+                    errors.Add((component.Id, item, $"{prefix}repeats item {seen[Normalize(items[index].Text)]}"));
+                }
+
+                if (CiteProblem(items[index].Cite, component, sourceLines) is { } citeProblem)
+                {
+                    errors.Add((component.Id, item, prefix + citeProblem));
+                }
+            }
+        }
+
+        return errors
+            .OrderBy(e => e.Id, StringComparer.Ordinal)
+            .ThenBy(e => e.Item)
+            .Select(e => e.Message)
+            .ToList();
+    }
+
+    private static string UnknownId(string id, IEnumerable<string> componentIds, IReadOnlyDictionary<string, string>? fileOf)
+    {
+        var message = $"{id}: not a component in components.json";
+        if (fileOf?.TryGetValue(id, out var file) == true)
+        {
+            message += $" ({file})";
+        }
+
+        var match = componentIds.FirstOrDefault(c => string.Equals(c, id, StringComparison.OrdinalIgnoreCase));
+        return match is null ? message : $"{message}; did you mean '{match}'?";
+    }
+
+    /// <summary>One plain markdown line: no HTML or links (they would render as something else), balanced code spans.</summary>
+    private static string? TextProblem(string text)
+    {
+        if (string.IsNullOrWhiteSpace(text))
+        {
+            return "text is empty";
+        }
+
+        if (text.Contains('\n') || text.Contains('\r'))
+        {
+            return "text must be a single line";
+        }
+
+        if (text.Trim().Length > MaxTextLength)
+        {
+            return $"text is {text.Trim().Length} characters; keep it under {MaxTextLength}";
+        }
+
+        if (text.Count(c => c == '`') % 2 != 0)
+        {
+            return "text has an unclosed ` code span";
+        }
+
+        var outsideCode = CodeSpan().Replace(text, "");
+        if (HtmlTag().IsMatch(outsideCode))
+        {
+            return "text contains HTML; put code in `backticks`";
+        }
+
+        return outsideCode.Contains("](") ? "text contains a link" : null;
+    }
+
+    private static string? CiteProblem(
+        string cite, Component component, IReadOnlyDictionary<string, IReadOnlyList<string>> sourceLines)
+    {
+        if (Citation.Parse(cite) is not { } citation)
+        {
+            return $"cite '{cite}' is not <file>:<line> or <file>:<start>-<end>";
+        }
+
+        var citable = component.Spans.Concat(component.Reaches ?? []).ToList();
+        var spans = citable.Where(s => s.File == citation.File).ToList();
+        if (spans.Count == 0)
+        {
+            return $"cite '{cite}' is not in the component's files: {string.Join(", ", citable.Select(s => s.File).Distinct())}";
+        }
+
+        // The render command checks every span file exists before validating; a missing one here is a caller bug.
+        var lines = sourceLines[citation.File];
+        if (citation.End > lines.Count)
+        {
+            return $"cite '{cite}' is past the end of the file ({lines.Count} lines)";
+        }
+
+        // Every code line must be citable, and the first and last lines must lie inside a citable span. Lines between
+        // two citable members (blank, comment, brace) are not code, so a citation may run across neighbouring helper
+        // members without claiming anything uncited, but it cannot start or end outside them.
+        bool Citable(int line) => spans.Any(s => s.Start <= line && line <= s.End);
+        if (Enumerable.Range(citation.Start, citation.LineCount).Any(n => !Citable(n) && (IsCode(lines[n - 1]) || n == citation.Start || n == citation.End)))
+        {
+            var where = component.Reaches is { Count: > 0 }
+                ? "the component's declaration and the helper code it runs"
+                : "the component's declaration";
+            return $"cite '{cite}' is outside {where} ({string.Join(", ", spans.Select(s => $"{s.Start}-{s.End}"))})";
+        }
+
+        if (citation.LineCount > MaxCitedLines)
+        {
+            return $"cite '{cite}' spans {citation.LineCount} lines; cite at most {MaxCitedLines}";
+        }
+
+        return Enumerable.Range(citation.Start, citation.LineCount).Any(n => IsCode(lines[n - 1]))
+            ? null
+            : $"cite '{cite}' covers no code (only blank, comment or brace lines)";
+    }
+
+    /// <summary>Not blank, not only a comment, not only braces, parentheses and semicolons.</summary>
+    private static bool IsCode(string line)
+    {
+        var trimmed = line.Trim();
+        return trimmed.Length > 0
+            && !trimmed.StartsWith("//", StringComparison.Ordinal)
+            && !trimmed.StartsWith("/*", StringComparison.Ordinal)
+            && !trimmed.StartsWith('*')
+            && trimmed.Trim('{', '}', '(', ')', ';', ' ', '\t').Length > 0;
+    }
+
+    // "  Stores EACH   order. " and "stores each order." are the same responsibility.
+    private static string Normalize(string text) => Whitespace().Replace(text.Trim(), " ").ToLowerInvariant();
+
+    [GeneratedRegex("`[^`]*`")]
+    private static partial Regex CodeSpan();
+
+    [GeneratedRegex("<[A-Za-z/!]")]
+    private static partial Regex HtmlTag();
+
+    [GeneratedRegex(@"\s+")]
+    private static partial Regex Whitespace();
+}

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

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

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

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

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

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