Add check-selectors command and tooling

Introduce a new CLI command `check-selectors` that parses Motus locator calls from C# sources and validates them against live pages. Adds CheckSelectorsRunner to orchestrate the flow, SelectorParser (Roslyn) to extract locator calls, LocatorDispatcher to map parsed selectors to IPage locators, FingerprintScanner and SuggestionBuilder to find replacement candidates from manifest fingerprints, and SelectorCheckTablePrinter to render results. Supports --manifest (page URLs + fingerprints), --base-url, --ci (fail on broken selectors), and --json output. Wires the command into Program.cs, adds package references for Microsoft.CodeAnalysis.CSharp and Microsoft.Extensions.FileSystemGlobbing, and includes unit and integration tests for parsing, dispatching, printing, and end-to-end behavior.

Author: TorreyBetts

src/Motus.Cli/Commands/CheckSelectorsCommand.cs

@@ -0,0 +1,64 @@
+using System.CommandLine;
+using Motus.Cli.Services;
+
+namespace Motus.Cli.Commands;
+
+public static class CheckSelectorsCommand
+{
+    public static Command Build()
+    {
+        var globArg = new Argument<string>("glob")
+        {
+            Description = "Glob pattern for C# source files to scan (e.g. \"./Tests/**/*.cs\")"
+        };
+
+        var manifestOpt = new Option<string?>("--manifest")
+        {
+            Description = "Path to a *.selectors.json manifest. When provided, selectors are checked against their recorded PageUrl."
+        };
+
+        var baseUrlOpt = new Option<string?>("--base-url")
+        {
+            Description = "Base URL to check every selector against. Required when --manifest is not provided."
+        };
+
+        var ciOpt = new Option<bool>("--ci")
+        {
+            Description = "Exit with a non-zero status code if any selector is broken."
+        };
+
+        var jsonOpt = new Option<string?>("--json")
+        {
+            Description = "Write the full check results as JSON to the given path."
+        };
+
+        var cmd = new Command("check-selectors", "Validate recorded selectors against live pages")
+        {
+            globArg,
+            manifestOpt,
+            baseUrlOpt,
+            ciOpt,
+            jsonOpt,
+        };
+
+        cmd.SetAction(async (parseResult, ct) =>
+        {
+            var glob = parseResult.GetValue(globArg)!;
+            var manifest = parseResult.GetValue(manifestOpt);
+            var baseUrl = parseResult.GetValue(baseUrlOpt);
+            var ci = parseResult.GetValue(ciOpt);
+            var jsonPath = parseResult.GetValue(jsonOpt);
+
+            if (manifest is null && baseUrl is null)
+            {
+                Console.Error.WriteLine("error: either --manifest or --base-url must be provided.");
+                return 2;
+            }
+
+            var runner = new CheckSelectorsRunner();
+            return await runner.RunAsync(glob, manifest, baseUrl, ci, jsonPath, ct);
+        });
+
+        return cmd;
+    }
+}

src/Motus.Cli/Motus.Cli.csproj

@@ -26,6 +26,8 @@
 
   <ItemGroup>
     <PackageReference Include="System.CommandLine" Version="2.0.0-beta5.25277.114" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" />
+    <PackageReference Include="Microsoft.Extensions.FileSystemGlobbing" Version="8.0.0" />
   </ItemGroup>
 
   <ItemGroup>

src/Motus.Cli/Program.cs

@@ -11,6 +11,7 @@
     ScreenshotCommand.Build(),
     PdfCommand.Build(),
     TraceCommand.Build(),
+    CheckSelectorsCommand.Build(),
 };
 
 var config = new CommandLineConfiguration(root);

src/Motus.Cli/Services/CheckSelectorsRunner.cs

@@ -0,0 +1,285 @@
+using System.Text.Json;
+using Motus;
+using Motus.Abstractions;
+using Motus.Cli.Commands;
+using Motus.Selectors;
+
+namespace Motus.Cli.Services;
+
+/// <summary>
+/// Orchestrates <c>motus check-selectors</c>: parse C# sources for locator calls,
+/// navigate a real browser to the relevant page(s), record whether each selector
+/// still resolves to exactly one element, and emit a colored summary table plus
+/// optional JSON output. Returns the command's process exit code.
+/// </summary>
+internal sealed class CheckSelectorsRunner
+{
+    private readonly TextWriter _stdout;
+    private readonly TextWriter _stderr;
+    private readonly bool _useColor;
+
+    internal CheckSelectorsRunner(
+        TextWriter? stdout = null, TextWriter? stderr = null, bool? useColor = null)
+    {
+        _stdout = stdout ?? Console.Out;
+        _stderr = stderr ?? Console.Error;
+        _useColor = useColor ?? !Console.IsOutputRedirected;
+    }
+
+    internal async Task<int> RunAsync(
+        string glob,
+        string? manifestPath,
+        string? baseUrl,
+        bool ci,
+        string? jsonOutputPath,
+        CancellationToken ct)
+    {
+        // 1. Parse selectors from C# sources.
+        SelectorParseResult parseResult;
+        try
+        {
+            parseResult = await SelectorParser.ParseGlobAsync(
+                glob, Directory.GetCurrentDirectory(), ct).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            _stderr.WriteLine($"error: failed to parse sources: {ex.Message}");
+            return 2;
+        }
+
+        foreach (var w in parseResult.Warnings)
+            _stderr.WriteLine($"warning: {w.SourceFile}:{w.SourceLine}: {w.Message}");
+
+        if (parseResult.Selectors.Count == 0)
+        {
+            _stdout.WriteLine("No locator calls found. Nothing to check.");
+            return 0;
+        }
+
+        // 2. Load manifest if supplied.
+        SelectorManifest? manifest = null;
+        if (manifestPath is not null)
+        {
+            try
+            {
+                var json = await File.ReadAllTextAsync(manifestPath, ct).ConfigureAwait(false);
+                manifest = JsonSerializer.Deserialize(
+                    json, SelectorManifestJsonContext.Default.SelectorManifest);
+                if (manifest is null)
+                {
+                    _stderr.WriteLine($"error: manifest '{manifestPath}' deserialized to null.");
+                    return 2;
+                }
+            }
+            catch (Exception ex)
+            {
+                _stderr.WriteLine($"error: failed to load manifest '{manifestPath}': {ex.Message}");
+                return 2;
+            }
+        }
+
+        var manifestLookup = manifest is null
+            ? null
+            : BuildManifestLookup(manifest);
+
+        // 3. Build URL groups + the initial result list (skipped rows already materialized).
+        var results = new List<SelectorCheckResult>();
+        var groups = new Dictionary<string, List<(ParsedSelector Parsed, SelectorEntry? Entry)>>(StringComparer.Ordinal);
+
+        foreach (var selector in parseResult.Selectors)
+        {
+            if (selector.IsInterpolated)
+            {
+                results.Add(ToSkipped(selector,
+                    pageUrl: "",
+                    note: "interpolated selector cannot be validated statically"));
+                continue;
+            }
+
+            if (manifestLookup is not null)
+            {
+                if (!manifestLookup.TryGetValue((selector.Selector, selector.LocatorMethod), out var entry))
+                {
+                    results.Add(ToSkipped(selector,
+                        pageUrl: "",
+                        note: "no manifest entry; cannot determine page URL"));
+                    continue;
+                }
+
+                AddToGroup(groups, entry.PageUrl, selector, entry);
+            }
+            else
+            {
+                AddToGroup(groups, baseUrl!, selector, entry: null);
+            }
+        }
+
+        if (groups.Count == 0)
+        {
+            PrintAndWriteOutputs(results, jsonOutputPath);
+            return ExitCodeFor(results, ci);
+        }
+
+        // 4. Launch browser and check each URL group.
+        IBrowser? browser = null;
+        try
+        {
+            try
+            {
+                var launchOptions = new LaunchOptions
+                {
+                    Headless = true,
+                    ExecutablePath = BrowserPathHelper.Resolve(),
+                };
+                browser = await MotusLauncher.LaunchAsync(launchOptions, ct).ConfigureAwait(false);
+            }
+            catch (FileNotFoundException)
+            {
+                _stderr.WriteLine("error: no browser found. Run 'motus install' first.");
+                return 2;
+            }
+            catch (Exception ex)
+            {
+                _stderr.WriteLine($"error: failed to launch browser: {ex.Message}");
+                return 2;
+            }
+
+            var context = await browser.NewContextAsync().ConfigureAwait(false);
+            var page = await context.NewPageAsync().ConfigureAwait(false);
+
+            foreach (var (url, items) in groups)
+            {
+                try
+                {
+                    await page.GotoAsync(url, new NavigationOptions { WaitUntil = WaitUntil.Load })
+                        .ConfigureAwait(false);
+                }
+                catch (Exception ex)
+                {
+                    foreach (var item in items)
+                    {
+                        results.Add(ToSkipped(item.Parsed,
+                            pageUrl: url,
+                            note: $"navigation failed: {ex.Message}"));
+                    }
+                    continue;
+                }
+
+                foreach (var (parsed, entry) in items)
+                {
+                    ct.ThrowIfCancellationRequested();
+                    results.Add(await CheckOneAsync(page, parsed, entry, url, ct).ConfigureAwait(false));
+                }
+            }
+        }
+        finally
+        {
+            if (browser is not null)
+                await browser.CloseAsync().ConfigureAwait(false);
+        }
+
+        PrintAndWriteOutputs(results, jsonOutputPath);
+        return ExitCodeFor(results, ci);
+    }
+
+    private async Task<SelectorCheckResult> CheckOneAsync(
+        IPage page, ParsedSelector parsed, SelectorEntry? entry, string pageUrl, CancellationToken ct)
+    {
+        int count;
+        try
+        {
+            var locator = LocatorDispatcher.Dispatch(page, parsed);
+            count = await locator.CountAsync().ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            return new SelectorCheckResult(
+                SelectorCheckStatus.Broken,
+                parsed.Selector, parsed.LocatorMethod, parsed.SourceFile, parsed.SourceLine,
+                pageUrl, MatchCount: 0, Suggestion: null, Note: $"dispatch error: {ex.Message}");
+        }
+
+        var status = count switch
+        {
+            0 => SelectorCheckStatus.Broken,
+            1 => SelectorCheckStatus.Healthy,
+            _ => SelectorCheckStatus.Ambiguous,
+        };
+
+        string? suggestion = null;
+        if (status == SelectorCheckStatus.Broken && entry is not null)
+        {
+            var candidate = await FingerprintScanner.FindMatchAsync(page, entry.Fingerprint, ct)
+                .ConfigureAwait(false);
+            if (candidate is not null)
+                suggestion = SuggestionBuilder.Build(candidate);
+        }
+
+        return new SelectorCheckResult(
+            status,
+            parsed.Selector, parsed.LocatorMethod, parsed.SourceFile, parsed.SourceLine,
+            pageUrl, MatchCount: count, Suggestion: suggestion, Note: null);
+    }
+
+    private void PrintAndWriteOutputs(List<SelectorCheckResult> results, string? jsonOutputPath)
+    {
+        SelectorCheckTablePrinter.Print(results, _stdout, _useColor);
+
+        if (jsonOutputPath is not null)
+        {
+            try
+            {
+                var dir = Path.GetDirectoryName(jsonOutputPath);
+                if (!string.IsNullOrEmpty(dir))
+                    Directory.CreateDirectory(dir);
+                var json = JsonSerializer.Serialize(
+                    results, CheckResultsJsonContext.Default.ListSelectorCheckResult);
+                File.WriteAllText(jsonOutputPath, json);
+            }
+            catch (Exception ex)
+            {
+                _stderr.WriteLine($"warning: failed to write JSON output to '{jsonOutputPath}': {ex.Message}");
+            }
+        }
+    }
+
+    private static int ExitCodeFor(IReadOnlyList<SelectorCheckResult> results, bool ci)
+    {
+        if (!ci)
+            return 0;
+        foreach (var r in results)
+        {
+            if (r.Status == SelectorCheckStatus.Broken)
+                return 1;
+        }
+        return 0;
+    }
+
+    private static Dictionary<(string Selector, string LocatorMethod), SelectorEntry> BuildManifestLookup(
+        SelectorManifest manifest)
+    {
+        var map = new Dictionary<(string, string), SelectorEntry>();
+        foreach (var entry in manifest.Entries)
+            map[(entry.Selector, entry.LocatorMethod)] = entry;
+        return map;
+    }
+
+    private static void AddToGroup(
+        Dictionary<string, List<(ParsedSelector, SelectorEntry?)>> groups,
+        string url,
+        ParsedSelector parsed,
+        SelectorEntry? entry)
+    {
+        if (!groups.TryGetValue(url, out var list))
+        {
+            list = new List<(ParsedSelector, SelectorEntry?)>();
+            groups[url] = list;
+        }
+        list.Add((parsed, entry));
+    }
+
+    private static SelectorCheckResult ToSkipped(ParsedSelector s, string pageUrl, string note) =>
+        new(SelectorCheckStatus.Skipped,
+            s.Selector, s.LocatorMethod, s.SourceFile, s.SourceLine,
+            pageUrl, MatchCount: 0, Suggestion: null, Note: note);
+}