@phuc1403/musketeer 0.9.0 → 0.11.0

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

@@ -0,0 +1,27 @@
+using LogicalComponents;
+
+// Entry point: dispatches to one command per pipeline step. Anything unknown prints usage and exits 1.
+// candidates, extract and render report on stderr (their artifact is a file); the others report on stdout.
+return args switch
+{
+    ["candidates", .. var rest] => await CandidatesCommand.RunAsync(rest, Console.Error),
+    ["classify-batches", .. var rest] => await ClassifyBatchesCommand.RunAsync(rest, Console.Out),
+    ["classify-merge", .. var rest] => await ClassifyMergeCommand.RunAsync(rest, Console.Out),
+    ["extract", .. var rest] => await ExtractCommand.RunAsync(rest, Console.Error),
+    ["batches", .. var rest] => await BatchesCommand.RunAsync(rest, Console.Out),
+    ["prune", .. var rest] => await PruneCommand.RunAsync(rest, Console.Out),
+    ["render", .. var rest] => await RenderCommand.RunAsync(rest, Console.Error),
+    _ => PrintUsage(),
+};
+
+static int PrintUsage()
+{
+    Console.Error.WriteLine(CandidatesCommand.Usage);
+    Console.Error.WriteLine(ClassifyBatchesCommand.Usage);
+    Console.Error.WriteLine(ClassifyMergeCommand.Usage);
+    Console.Error.WriteLine(ExtractCommand.Usage);
+    Console.Error.WriteLine(BatchesCommand.Usage);
+    Console.Error.WriteLine(PruneCommand.Usage);
+    Console.Error.WriteLine(RenderCommand.Usage);
+    return 1;
+}

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

@@ -0,0 +1,76 @@
+using System.Text.RegularExpressions;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// Pure rules for which loaded projects the extractor keeps: no test projects, and one project per
+/// multi-targeted csproj. Kept free of Roslyn types so they are unit-testable from plain strings.
+/// </summary>
+public static partial class ProjectFilters
+{
+    /// <summary>
+    /// A test project lives under a <c>tests</c>/<c>test</c> folder, is named like one
+    /// (<c>.Tests</c>, <c>.UnitTests</c>, <c>.IntegrationTests</c>, <c>.Test</c>, <c>.Specs</c>), or its project
+    /// file carries a test marker (test SDK, <c>IsTestProject</c>, or a test-framework package).
+    /// Test-support libraries such as <c>Foo.Testing</c> are deliberately kept: nothing here can tell them apart
+    /// from source, and their types can be excluded through config.
+    /// </summary>
+    public static bool IsTestProject(string relativePath, string projectFileText)
+    {
+        var segments = relativePath.Split('/', '\\');
+        if (segments.Any(s => s.Equals("tests", StringComparison.OrdinalIgnoreCase)
+                || s.Equals("test", StringComparison.OrdinalIgnoreCase)))
+        {
+            return true;
+        }
+
+        return TestProjectName().IsMatch(Path.GetFileNameWithoutExtension(relativePath))
+            || TestProjectMarker().IsMatch(projectFileText);
+    }
+
+    /// <summary>
+    /// Orders the target framework in a loaded multi-target project name such as <c>Foo(net10.0)</c>.
+    /// Families rank .NET Framework &lt; netstandard &lt; netcoreapp &lt; net5+; versions order within a family.
+    /// </summary>
+    public static (int Family, Version Version) TargetFrameworkRank(string loadedProjectName)
+    {
+        var match = TargetFrameworkSuffix().Match(loadedProjectName);
+        if (!match.Success)
+        {
+            return (0, new Version(0, 0));
+        }
+
+        // Drop an OS suffix: net9.0-windows ranks as net9.0.
+        var tfm = match.Groups["tfm"].Value.ToLowerInvariant().Split('-')[0];
+        return tfm switch
+        {
+            _ when tfm.StartsWith("netstandard") => (1, ParseVersion(tfm["netstandard".Length..])),
+            _ when tfm.StartsWith("netcoreapp") => (2, ParseVersion(tfm["netcoreapp".Length..])),
+            _ when tfm.Contains('.') => (3, ParseVersion(tfm["net".Length..])),
+            // .NET Framework monikers pack the version into digits: net472 is 4.7.2.
+            _ => (0, ParseVersion(string.Join('.', tfm["net".Length..].ToCharArray()))),
+        };
+    }
+
+    /// <summary><c>Foo(net10.0)</c> becomes <c>Foo</c>; a name without a framework suffix is returned as-is.</summary>
+    public static string StripTargetFramework(string loadedProjectName)
+    {
+        var match = TargetFrameworkSuffix().Match(loadedProjectName);
+        return match.Success ? match.Groups["name"].Value : loadedProjectName;
+    }
+
+    private static Version ParseVersion(string text) =>
+        Version.TryParse(text.Contains('.') ? text : text + ".0", out var version) ? version : new Version(0, 0);
+
+    // Case-sensitive on purpose: "Foo.Contest" and "Latest.Feeds" must not look like test projects.
+    [GeneratedRegex(@"\.\w*Tests?$|\.Specs?$")]
+    private static partial Regex TestProjectName();
+
+    [GeneratedRegex(
+        @"<IsTestProject>\s*true\s*</IsTestProject>|Sdk=""MSTest\.Sdk|Include=""(Microsoft\.NET\.Test\.Sdk|xunit|xunit\.v3|xunit\.core|xunit\.v3\.core|NUnit|MSTest|MSTest\.TestFramework|Microsoft\.Testing\.Platform)""",
+        RegexOptions.IgnoreCase)]
+    private static partial Regex TestProjectMarker();
+
+    [GeneratedRegex(@"^(?<name>.+)\((?<tfm>net[^)]*)\)$")]
+    private static partial Regex TargetFrameworkSuffix();
+}

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

@@ -0,0 +1,132 @@
+using System.Text.Json;
+
+namespace LogicalComponents;
+
+/// <summary>
+/// <c>prune --resp &lt;dir&gt; --verify &lt;dir&gt; --out &lt;dir&gt;</c>: applies the verifier agents' verdicts. For every
+/// <c>resp/batch-NN.json</c> it reads <c>verify/batch-NN.json</c> — <c>{ "&lt;id&gt;": [ { "item": 1, "supported": true,
+/// "reason": "..." } ] }</c> — and writes the batch without its unsupported items to <c>--out</c>. The agents' files are
+/// never edited, so pruning is repeatable. Every item needs exactly one verdict: an unjudged claim is not verified, so
+/// any gap fails the step (exit 3) before anything is written. Exit codes: 0 written, 1 usage, 3 verdicts incomplete.
+/// </summary>
+public static class PruneCommand
+{
+    public const string Usage = "usage: LogicalComponents prune --resp <dir> --verify <dir> --out <dir>";
+
+    public sealed record Verdict(int Item, bool Supported, string? Reason);
+
+    private static readonly JsonSerializerOptions ReadOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+        AllowDuplicateProperties = false,
+    };
+
+    public static async Task<int> RunAsync(string[] args, TextWriter output)
+    {
+        if (args is not ["--resp", var respDir, "--verify", var verifyDir, "--out", var outDir]
+            || !Directory.Exists(respDir) || !Directory.Exists(verifyDir))
+        {
+            await output.WriteLineAsync(Usage);
+            return 1;
+        }
+
+        var problems = new List<string>();
+        var pruned = new List<(string File, SortedDictionary<string, List<Responsibility>> Kept)>();
+        var removed = new List<string>();
+        var emptied = new List<string>();
+
+        foreach (var respFile in Directory.EnumerateFiles(respDir, "batch-*.json").Order(StringComparer.Ordinal))
+        {
+            var name = Path.GetFileName(respFile);
+            var batch = ResponsibilityBatches.Load([respFile], ReadOptions);
+            problems.AddRange(batch.Problems);
+            var verdicts = ReadVerdicts(Path.Combine(verifyDir, name), name, problems);
+            if (verdicts is null)
+            {
+                continue;
+            }
+
+            var kept = new SortedDictionary<string, List<Responsibility>>(StringComparer.Ordinal);
+            foreach (var (id, items) in batch.Responsibilities.OrderBy(r => r.Key, StringComparer.Ordinal))
+            {
+                var judged = verdicts.GetValueOrDefault(id) ?? [];
+                problems.AddRange(judged.Where(v => v.Item < 1 || v.Item > items.Count)
+                    .Select(v => $"{id}[{v.Item}]: verdict for an item that does not exist ({name})"));
+
+                kept[id] = [];
+                for (var item = 1; item <= items.Count; item++)
+                {
+                    var forItem = judged.Where(v => v.Item == item).ToList();
+                    if (forItem.Count != 1)
+                    {
+                        problems.Add($"{id}[{item}]: {(forItem.Count == 0 ? "no verdict" : "more than one verdict")} ({name})");
+                    }
+                    else if (forItem[0].Supported)
+                    {
+                        kept[id].Add(items[item - 1]);
+                    }
+                    else
+                    {
+                        removed.Add($"removed {id}[{item}]: {forItem[0].Reason ?? "(no reason given)"}");
+                    }
+                }
+
+                if (items.Count > 0 && kept[id].Count == 0)
+                {
+                    emptied.Add($"empty {id}: every responsibility was unsupported");
+                }
+            }
+
+            problems.AddRange(verdicts.Keys.Where(id => !batch.Responsibilities.ContainsKey(id))
+                .Order(StringComparer.Ordinal)
+                .Select(id => $"{id}: verdicts for a component the batch does not answer ({name})"));
+            pruned.Add((name, kept));
+        }
+
+        if (problems.Count > 0)
+        {
+            foreach (var problem in problems)
+            {
+                await output.WriteLineAsync(problem);
+            }
+
+            return 3;
+        }
+
+        Directory.CreateDirectory(outDir);
+        foreach (var (file, kept) in pruned)
+        {
+            await File.WriteAllBytesAsync(Path.Combine(outDir, file), ComponentsFile.ToJson(kept));
+        }
+
+        foreach (var line in removed.Concat(emptied))
+        {
+            await output.WriteLineAsync(line);
+        }
+
+        await output.WriteLineAsync($"{removed.Count} removed, {emptied.Count} empty");
+        return 0;
+    }
+
+    private static Dictionary<string, List<Verdict>>? ReadVerdicts(string path, string name, List<string> problems)
+    {
+        if (!File.Exists(path))
+        {
+            problems.Add($"{name}: no verdict file");
+            return null;
+        }
+
+        try
+        {
+            var verdicts = JsonSerializer.Deserialize<Dictionary<string, List<Verdict>?>>(File.ReadAllText(path), ReadOptions) ?? [];
+            return verdicts.ToDictionary(v => v.Key, v => v.Value ?? [], StringComparer.Ordinal);
+        }
+        catch (Exception e) when (e is IOException or UnauthorizedAccessException or JsonException)
+        {
+            problems.Add($"{name}: not a valid verdict file ({e.Message})");
+            return null;
+        }
+    }
+}

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