diff --git a/CHANGELOG.md b/CHANGELOG.md index b26f3f495..adbc4721b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -224,6 +224,15 @@ Conventions for contributors: instead of `0,0,8,0`. A flip back to left-to-right with a declared physical value could also skip the write and leave the right-to-left value on the control. +- ReactorGallery search keeps complete samples that contain ellipses in comments + or display text, restoring the Pan and `OpacityTransition` examples in + `winapp find-ui --source reactor`. Code elisions, map-token fill-ins, and placeholders + in URI-shaped string literals are filtered, including Image and MediaPlayerElement + sources and displayed URI templates. An independent coverage check catches missing + cards even after index regeneration + ([issue #1020](https://github.com/microsoft/microsoft-ui-reactor/issues/1020), + [spec 064 §3.2](docs/specs/064-search-index-framework-concepts.md#32-every-clean-card-is-emitted)). + ### Security ## [0.1.0-preview.18] — 2026-11-12 diff --git a/TESTING.md b/TESTING.md index 6cee93ff1..359cc258e 100644 --- a/TESTING.md +++ b/TESTING.md @@ -232,6 +232,7 @@ Some tests here parse repo *sources* with Roslyn rather than exercising Reactor | `GallerySnippetAgreementTests` | A `SampleCard` snippet uses a lowerCamelCase name that does not exist in the live code beside it — the snippet renamed, or the card did and the snippet did not. Direction is snippet → live only: a snippet may omit, it may not invent. | | `GallerySampleLintTests` | An ItemsView view builder returns something other than an item-container root; a shape paints with `.Background(...)` instead of `Fill`/`Stroke`; or an `ms-appx` asset is missing or not copied to the output. Also checks [PUA glyph fonts](#pua-glyph-fonts-in-gallery-samples) in live gallery code and displayed snippets. | | `SearchIndexGeneratorTests` | `samples/ReactorGallery/reactor-search-index.json` is stale. Regenerate with `dotnet run --project tools/Reactor.SearchIndex`. | +| `SearchIndexCoverageTests` | A routed Gallery card is missing or out of order in the index, or a [manifest entry](tests/Reactor.Tests/Tooling/SearchIndexCoverageTests.cs) no longer names a source card. This check still catches omissions after index regeneration. | A snippet-agreement failure names the page, line, card title and identifier, and says which of the two sides to move. There is no allowlist: fix the snippet or fix the card. diff --git a/docs/specs/064-search-index-framework-concepts.md b/docs/specs/064-search-index-framework-concepts.md index 97a193f68..3aad4039c 100644 --- a/docs/specs/064-search-index-framework-concepts.md +++ b/docs/specs/064-search-index-framework-concepts.md @@ -109,12 +109,23 @@ one snippet, and the contract's `samples` array was always plural. - An editorial `sampleOverride` still defines the **first** sample (replacing its header, its code, or both, or standing alone when no card qualifies); the page's remaining clean cards follow it. -- The per-card REAL-CODE-ONLY rule is unchanged: a card that abbreviates with a - placeholder is passed over, and a page with no clean card at all still fails - generation. +- The per-card REAL-CODE-ONLY rule skips code elisions, comment-only snippets, + explicit omission comments, map-token fill-ins, and placeholders in URI-shaped + literals. Ordinary comments and display strings can contain ellipses. See the + [generator's rules](../../tools/Reactor.SearchIndex/README.md#guarantees--gate) + for the supported literal arguments and omission markers. A page without a usable + sample still requires an editorial override. - Headers are deduplicated case-insensitively — two same-titled cards would ship two indistinguishable scenarios. +The byte-comparison gate checks freshness. As a separate coverage check for +[#1020](https://github.com/microsoft/microsoft-ui-reactor/issues/1020), +`SearchIndexCoverageTests` enumerates the routed source cards and compares their +headers and order with the index. Its manifest records deliberate omissions by +card with a reason. Override headers come directly from `editorial.json` and apply +to the first non-skipped card, or provide a standalone sample header. A missing +card fails this test even when the index has already been regenerated. + ### 3.3 Prose is lifted from the skills by marker `curatedKeywords` and `docs` are authored in `editorial.json`. `details` is not: diff --git a/samples/ReactorGallery/README.md b/samples/ReactorGallery/README.md index 5fa410483..b441da315 100644 --- a/samples/ReactorGallery/README.md +++ b/samples/ReactorGallery/README.md @@ -134,6 +134,11 @@ dotnet run --project tools/Reactor.SearchIndex ``` A `Reactor.Tests` gate byte-compares the committed file, so a stale index fails CI. +`SearchIndexCoverageTests` also checks for cards that are missing from a regenerated +index. Record deliberate omissions in the +[coverage manifest](../../tests/Reactor.Tests/Tooling/SearchIndexCoverageTests.cs). +Remove an omission entry when its card becomes a complete sample. + Curate keywords and overrides in `tools/Reactor.SearchIndex/editorial.json`, never in the generated JSON. diff --git a/samples/ReactorGallery/reactor-search-index.json b/samples/ReactorGallery/reactor-search-index.json index d053f6be6..df472a1ae 100644 --- a/samples/ReactorGallery/reactor-search-index.json +++ b/samples/ReactorGallery/reactor-search-index.json @@ -2157,6 +2157,11 @@ "language": "csharp", "code": "var (tapLog, setTapLog) = UseState(\"Tap, double-tap, or right-tap the card.\");\n\nBorder(TextBlock(tapLog))\n .IsTabStop(true)\n .AutomationName(\"Tap surface\")\n .OnTapped((_, _) => setTapLog(\"Tapped.\"))\n .OnDoubleTapped((_, _) => setTapLog(\"Double-tapped.\"))\n .OnRightTapped((_, _) => setTapLog(\"Right-tapped.\"))\n .OnLongPress(onTriggered: () => setTapLog(\"Long-pressed.\"), enableMouseEmulation: true)\n // Reachable by Tab is not the same as operable — pair the tap with Enter/Space.\n .OnKeyDown((_, e) =>\n {\n if (e.Key is not (VirtualKey.Enter or VirtualKey.Space)) return;\n setTapLog(\"Activated from the keyboard.\");\n e.Handled = true;\n })" }, + { + "header": "Pan — drag with the phase lifecycle", + "language": "csharp", + "code": "var (offsetX, moveX) = UseReducer(0.0);\nvar (offsetY, moveY) = UseReducer(0.0);\n\nBorder(TextBlock(\"Drag me\"))\n .OnPan(\n onChanged: e =>\n {\n // Functional updaters, NOT setOffsetX(offsetX + ...): several onChanged\n // callbacks can land between two renders, and each would read the same\n // stale captured value and overwrite the one before it.\n moveX(x => x + e.Delta.X);\n moveY(y => y + e.Delta.Y);\n },\n minimumDistance: 4)\n .Translation((float)offsetX, (float)offsetY, 0)" + }, { "header": "Pinch and rotate", "language": "csharp", @@ -3271,6 +3276,11 @@ "nugetPackage": "Microsoft.UI.Reactor", "galleryRoute": "transitions", "samples": [ + { + "header": "OpacityTransition", + "language": "csharp", + "code": "var (visible, setVisible) = UseState(true);\n\nTextBlock(\"Opacity is animated, not toggled\")\n .Opacity(visible ? 1.0 : 0.0)\n .OpacityTransition(TimeSpan.FromMilliseconds(400))\n// Omit the TimeSpan for the 300ms default. Fading to 0 leaves the element in the tree\n// and still occupying its layout slot -- use .Transition(...) if you want it to leave." + }, { "header": "ScaleTransition", "language": "csharp", diff --git a/tests/Reactor.Tests/Tooling/GallerySources.cs b/tests/Reactor.Tests/Tooling/GallerySources.cs index ae69b8a0d..5c8f2e58d 100644 --- a/tests/Reactor.Tests/Tooling/GallerySources.cs +++ b/tests/Reactor.Tests/Tooling/GallerySources.cs @@ -43,7 +43,7 @@ public static string RepoRoot() /// Includes supporting source files so constants and partial types bind across files. public static IReadOnlyList<(string Path, SyntaxNode Root)> AllSources() => ReadSources(GalleryDir()); - static IReadOnlyList<(string Path, SyntaxNode Root)> ReadSources(string directory) + internal static IReadOnlyList<(string Path, SyntaxNode Root)> ReadSources(string directory) { Assert.True(Directory.Exists(directory), $"gallery source directory not found at {directory}"); diff --git a/tests/Reactor.Tests/Tooling/SearchIndexCoverageTests.cs b/tests/Reactor.Tests/Tooling/SearchIndexCoverageTests.cs new file mode 100644 index 000000000..512fc13dc --- /dev/null +++ b/tests/Reactor.Tests/Tooling/SearchIndexCoverageTests.cs @@ -0,0 +1,338 @@ +using System.Text.Json; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.CSharp.Syntax; +using Microsoft.UI.Reactor.SearchIndex; +using Xunit; + +namespace Microsoft.UI.Reactor.Tests.Tooling; + +public sealed class SearchIndexCoverageTests +{ + readonly record struct CardKey(string Control, string Title, int Occurrence = 1); + + // This manifest is reviewed against the page source. A new omission fails the test even + // if the generated JSON was refreshed. Remove an entry when its card starts shipping. + static readonly Dictionary Omissions = new() + { + [new("auto-suggest-box", "Filtered Results Display")] = "The Select projection is elided.", + [new("card", "Card with icon, heading, and body")] = "The icon Border is abbreviated.", + [new("color", "")] = "BrushSection computes the card title and code at runtime.", + [new("expander", "Basic Expander")] = "Additional content children are elided.", + [new("flex", "Grow & Shrink")] = "The child Borders have abbreviated content.", + [new("flip-view", "Data-Driven FlipView")] = "The item template's VStack children are elided.", + [new("grid", "Basic Grid")] = "Remaining grid cells are elided.", + [new("list-view", "Basic ListView")] = "Additional list items are elided.", + [new("list-view", "Animated edit (spec 042)")] = "The mutation signature and item template are elided.", + [new("rich-text-block", "Inline hyperlinks & embedded UI")] = "The embedded button callback is elided.", + [new("scroll-view", "Horizontal ScrollView (modern)")] = "The HStack content is elided.", + [new("scroll-view", "Classic ScrollViewer (legacy)")] = "The VStack content is elided.", + [new("spacing", "Spacing Scale")] = "The card's snippet is a comment describing the scale.", + [new("tree-view", "Basic TreeView")] = "The Pictures subtree is elided.", + [new("typography", "Type Ramp")] = "The code is assembled from the type ramp at runtime.", + }; + + [Fact] + public void EveryGalleryCard_IsIndexedOrAccountedFor() + { + var root = GallerySources.RepoRoot(); + var gallery = GallerySources.GalleryDir(); + using var editorial = JsonDocument.Parse( + File.ReadAllText(Path.Join(root, "tools", "Reactor.SearchIndex", "editorial.json")), + new JsonDocumentOptions { CommentHandling = JsonCommentHandling.Skip }); + using var index = JsonDocument.Parse(File.ReadAllText(Path.Join(gallery, "reactor-search-index.json"))); + var problems = CoverageProblems(gallery, editorial.RootElement, index.RootElement, Omissions); + Assert.True(problems.Count == 0, string.Join(Environment.NewLine, problems)); + } + + [Theory] + [InlineData("bin")] + [InlineData("obj")] + public void RegeneratedIndex_IgnoresBuildOutputPages(string outputDirectory) + { + using var gallery = new MiniGallery(betaRouted: true); + var editorialPath = gallery.WriteEditorial(""" + { "alpha": { "keywords": ["one", "two", "three"] }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + var omissions = new Dictionary<CardKey, string>(); + + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + + var generatedDirectory = Path.Join(gallery.GalleryDir, "ControlPages", "Nested", outputDirectory); + Directory.CreateDirectory(generatedDirectory); + File.WriteAllText(Path.Join(generatedDirectory, "AlphaPage.g.cs"), """ + class AlphaPage + { + object Render() => SampleCard("Generated", null, "Alpha().Generated();"); + } + """); + + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + } + + [Fact] + public void RegeneratedIndex_ReportsUnaccountedOmission() + { + using var gallery = new MiniGallery(betaRouted: true); + var editorialPath = gallery.WriteEditorial(""" + { "alpha": { "keywords": ["one", "two", "three"] }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + + List<string> Check(string code) + { + gallery.OverwriteAlphaPage($$""" + class AlphaPage + { + object Render() => VStack( + SampleCard("Before", null, "Alpha();"), + SampleCard("Probe", null, {{SyntaxFactory.Literal(code).Text}}), + SampleCard("After", null, "Alpha();")); + } + """); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + return CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, + new Dictionary<CardKey, string>()); + } + + // Generate a fresh index in both cases. The coverage check must still see a dropped card. + Assert.Empty(Check("Alpha(); // see Alpha(...), then continue")); + Assert.Contains(Check("Alpha(a, ...);"), problem => problem.Contains("Missing: [Probe]", StringComparison.Ordinal)); + } + + [Fact] + public void RegeneratedIndex_ReportsStaleManifestEntry() + { + using var gallery = new MiniGallery(betaRouted: true); + var editorialPath = gallery.WriteEditorial(""" + { "alpha": { "keywords": ["one", "two", "three"] }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + var omissions = new Dictionary<CardKey, string>(); + + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + + omissions.Add(new("alpha", "Removed card"), "The card was removed"); + var problem = Assert.Single(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + Assert.Equal("alpha / Removed card (1): stale manifest entry (The card was removed).", problem); + } + + [Theory] + [InlineData("""{ "header": "Curated" }""", "Curated")] + [InlineData("""{ "code": "Alpha().Configured();" }""", "Alpha basic")] + [InlineData("""{ "header": "Curated", "code": "Alpha().Configured();" }""", "Curated")] + public void RegeneratedIndex_AppliesEditorialOverride(string sampleOverride, string expectedHeader) + { + using var gallery = new MiniGallery(betaRouted: true); + var editorialPath = gallery.WriteEditorial($$""" + { "alpha": { "keywords": ["one", "two", "three"], "sampleOverride": {{sampleOverride}} }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + var samples = index.RootElement.GetProperty("controls")[0].GetProperty("samples"); + + Assert.Equal(expectedHeader, Assert.Single(samples.EnumerateArray()).GetProperty("header").GetString()); + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, + new Dictionary<CardKey, string>())); + } + + [Fact] + public void RegeneratedIndex_AppliesOverrideAfterSkippedCard() + { + using var gallery = new MiniGallery(betaRouted: true); + gallery.OverwriteAlphaPage(""" + class AlphaPage + { + object Render() => VStack( + SampleCard("Guidance", null, "// Guidance only"), + SampleCard("First", null, "Alpha();"), + SampleCard("curated", null, "Alpha().Alternate();"), + SampleCard("Later", null, "Alpha().Tuned();")); + } + """); + var editorialPath = gallery.WriteEditorial(""" + { "alpha": { "keywords": ["one", "two", "three"], "sampleOverride": { "header": "Curated" } }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + var omissions = new Dictionary<CardKey, string> + { + [new("alpha", "Guidance")] = "The snippet is comment-only", + }; + var samples = index.RootElement.GetProperty("controls")[0].GetProperty("samples"); + + Assert.Equal(new[] { "Curated", "Later" }, samples.EnumerateArray().Select(s => s.GetProperty("header").GetString())); + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + } + + [Fact] + public void RegeneratedIndex_UsesStandaloneEditorialOverride() + { + using var gallery = new MiniGallery(betaRouted: true); + gallery.OverwriteAlphaPage(""" + class AlphaPage + { + object Render() => SampleCard("Guidance", null, "// Guidance only"); + } + """); + var editorialPath = gallery.WriteEditorial(""" + { "alpha": { "keywords": ["one", "two", "three"], + "sampleOverride": { "header": "Curated", "code": "Alpha();" } }, + "beta": { "keywords": ["one", "two", "three"] } } + """); + using var editorial = JsonDocument.Parse(File.ReadAllText(editorialPath)); + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorialPath).Json); + var omissions = new Dictionary<CardKey, string> + { + [new("alpha", "Guidance")] = "The snippet is comment-only", + }; + var samples = index.RootElement.GetProperty("controls")[0].GetProperty("samples"); + + Assert.Equal("Curated", Assert.Single(samples.EnumerateArray()).GetProperty("header").GetString()); + Assert.Empty(CoverageProblems(gallery.GalleryDir, editorial.RootElement, index.RootElement, omissions)); + } + + static List<string> CoverageProblems(string gallery, JsonElement editorial, JsonElement index, + IReadOnlyDictionary<CardKey, string> omissions) + { + var registered = RegistryIds(gallery); + Assert.NotEmpty(registered); + var included = registered.Where(id => !IsExcluded(editorial, id)).ToArray(); + var indexed = index.GetProperty("controls").EnumerateArray().ToDictionary( + c => c.GetProperty("id").GetString()!, c => c.GetProperty("samples"), StringComparer.Ordinal); + Assert.Equal(included.Order(StringComparer.Ordinal), indexed.Keys.Order(StringComparer.Ordinal)); + + var routes = Routes(gallery); + var pageNames = included.Select(id => routes[id]).ToHashSet(StringComparer.Ordinal); + var pages = GallerySources.ReadSources(Path.Join(gallery, "ControlPages")) + .SelectMany(source => source.Root.DescendantNodes().OfType<ClassDeclarationSyntax>()) + .Where(page => pageNames.Contains(page.Identifier.ValueText)) + .ToDictionary(page => page.Identifier.ValueText, page => CardInvocations(page).ToArray(), StringComparer.Ordinal); + + var remainingOmissions = new Dictionary<CardKey, string>(omissions); + var problems = new List<string>(); + foreach (var id in included) + { + var expected = new List<string>(); + var occurrences = new Dictionary<string, int>(StringComparer.Ordinal); + foreach (var card in pages[routes[id]]) + { + var args = card.ArgumentList.Arguments; + var titleExpression = Argument(args, "title", 0); + var literalTitle = ReadOptionalLiteral(titleExpression); + var title = literalTitle?.Trim() ?? $"<{titleExpression}>"; + var count = occurrences.GetValueOrDefault(title) + 1; + occurrences[title] = count; + var key = new CardKey(id, title, count); + var sourceExpression = Argument(args, "sourceCode", 2); + var sourceCode = ReadOptionalLiteral(sourceExpression); + + if (remainingOmissions.Remove(key)) continue; + + if (literalTitle is null || sourceCode is null) + { + var field = literalTitle is null ? "title" : "sourceCode"; + problems.Add($"{id} / {title} ({count}): non-literal or absent {field} needs an explicit manifest entry."); + continue; + } + + expected.Add(title); + } + + var overrideHeader = ReadOverrideHeader(editorial, id); + if (overrideHeader is not null) + { + expected = expected.Skip(1) + .Where(header => !string.Equals(header, overrideHeader, StringComparison.OrdinalIgnoreCase)) + .Prepend(overrideHeader).ToList(); + } + + var actual = indexed[id].EnumerateArray().Select(s => s.GetProperty("header").GetString()!).ToArray(); + if (expected.SequenceEqual(actual)) continue; + + var missing = expected.Except(actual).ToArray(); + var unexpected = actual.Except(expected).ToArray(); + problems.Add($"{id}: expected {expected.Count}, got {actual.Length}. " + + $"Missing: [{string.Join(", ", missing)}]. " + + $"Unexpected: [{string.Join(", ", unexpected)}]. " + + "If both lists are empty, check the order or duplicate count."); + } + + problems.AddRange(remainingOmissions.Select(entry => + $"{entry.Key.Control} / {entry.Key.Title} ({entry.Key.Occurrence}): stale manifest entry ({entry.Value}).")); + return problems; + } + + static string[] RegistryIds(string gallery) + { + var registry = ReadSource(Path.Join(gallery, "ControlRegistry.cs")); + var all = registry.DescendantNodes().OfType<PropertyDeclarationSyntax>().Single(p => p.Identifier.ValueText == "All"); + var controls = all.DescendantNodes().OfType<ArrayCreationExpressionSyntax>().Single().Initializer + ?? throw new InvalidDataException("Missing ControlRegistry.All initializer."); + return controls.Expressions.Select(entry => ReadLiteral(entry switch + { + ImplicitObjectCreationExpressionSyntax creation => Argument(creation.ArgumentList.Arguments, "Tag", 4), + ObjectCreationExpressionSyntax { ArgumentList: { } args } => Argument(args.Arguments, "Tag", 4), + _ => throw new InvalidDataException($"Unknown ControlRegistry entry: {entry}"), + })).ToArray(); + } + + static Dictionary<string, string> Routes(string gallery) + { + return ReadSource(Path.Join(gallery, "PageRouter.cs")).DescendantNodes().OfType<SwitchExpressionArmSyntax>() + .Where(arm => arm.Pattern is ConstantPatternSyntax) + .GroupBy(arm => ReadLiteral(((ConstantPatternSyntax)arm.Pattern).Expression), StringComparer.Ordinal) + .ToDictionary(group => group.Key, group => group.Select(arm => arm.Expression.DescendantNodes().OfType<GenericNameSyntax>() + .Single(name => name.Identifier.ValueText == "Component").TypeArgumentList.Arguments.Single().GetLastToken().ValueText) + .Distinct(StringComparer.Ordinal).Single(), StringComparer.Ordinal); + } + + static IEnumerable<InvocationExpressionSyntax> CardInvocations(ClassDeclarationSyntax page) => + // Routed pages such as Transitions use nested components for their live cards. + page.DescendantNodes() + .OfType<InvocationExpressionSyntax>().Where(call => GallerySources.InvokedName(call) == "SampleCard"); + + static ExpressionSyntax? Argument(SeparatedSyntaxList<ArgumentSyntax> args, string name, int position) => + args.FirstOrDefault(a => a.NameColon?.Name.Identifier.ValueText == name)?.Expression + ?? (position < args.Count && args[position].NameColon is null ? args[position].Expression : null); + + static string ReadLiteral(ExpressionSyntax? syntax) => ReadOptionalLiteral(syntax) + ?? throw new InvalidDataException($"Expected a string literal, got: {syntax}"); + + static string? ReadOptionalLiteral(ExpressionSyntax? syntax) => + syntax is LiteralExpressionSyntax { RawKind: (int)SyntaxKind.StringLiteralExpression } literal + ? literal.Token.ValueText : null; + + static bool IsExcluded(JsonElement editorial, string id) => + editorial.TryGetProperty(id, out var entry) + && EditorialProperty(entry, "exclude").ValueKind == JsonValueKind.True; + + static string? ReadOverrideHeader(JsonElement editorial, string id) + { + if (!editorial.TryGetProperty(id, out var entry)) return null; + var sample = EditorialProperty(entry, "sampleOverride"); + return ReadField(sample, "header")?.Trim(); + } + + static string? ReadField(JsonElement element, string field) + { + var property = EditorialProperty(element, field); + return property.ValueKind == JsonValueKind.String && !string.IsNullOrWhiteSpace(property.GetString()) + ? property.GetString() : null; + } + + // Editorial field names are case-insensitive, while the control IDs are ordinal. + static JsonElement EditorialProperty(JsonElement element, string name) => element.ValueKind == JsonValueKind.Object + ? element.EnumerateObject().LastOrDefault(property => string.Equals(property.Name, name, StringComparison.OrdinalIgnoreCase)).Value + : default; + + static SyntaxNode ReadSource(string file) => CSharpSyntaxTree.ParseText(File.ReadAllText(file)).GetRoot(); +} diff --git a/tests/Reactor.Tests/Tooling/SearchIndexGeneratorTests.cs b/tests/Reactor.Tests/Tooling/SearchIndexGeneratorTests.cs index e981b620d..77f18bec7 100644 --- a/tests/Reactor.Tests/Tooling/SearchIndexGeneratorTests.cs +++ b/tests/Reactor.Tests/Tooling/SearchIndexGeneratorTests.cs @@ -4,7 +4,6 @@ using System.Linq; using System.Text; using System.Text.Json; -using System.Text.RegularExpressions; using Microsoft.UI.Reactor.SearchIndex; using Xunit; @@ -215,17 +214,24 @@ public void ExpectedControls_ArePresent() Assert.True(ids.Count >= 90, $"expected >=90 controls, got {ids.Count}"); } - // ── REAL CODE ONLY: no placeholder/abbreviation tokens survive (invariant #2) ─ + [Theory] + [InlineData("pointer-input", "Pan — drag with the phase lifecycle", ".OnPan(")] + [InlineData("transitions", "OpacityTransition", ".OpacityTransition(")] + public void GallerySamples_WithCommentEllipses_AreIndexed(string id, string header, string api) + { + var entry = Find(Parse(Generate().Json), id); + var sample = Assert.Single(entry.Samples, s => s.Header == header); + + Assert.Contains(api, sample.Code); + } [Fact] - public void Samples_ContainNoPlaceholderTokens() + public void Samples_ContainNoUnexpandedTemplateMarkers() { - var placeholder = new Regex(@",\s*\.\.\.|\.\.\.\s*\)|\(\s*\.\.\.|^\s*\.\.\.\s*$|\.\.\./|<your", RegexOptions.Multiline); foreach (var c in Parse(Generate().Json).Controls) { foreach (var code in c.Samples.Select(s => s.Code)) { - Assert.False(placeholder.IsMatch(code), $"{c.Id} sample has a placeholder token:\n{code}"); Assert.DoesNotContain("{{", code); } } diff --git a/tests/Reactor.Tests/Tooling/SearchIndexPlaceholderTests.cs b/tests/Reactor.Tests/Tooling/SearchIndexPlaceholderTests.cs new file mode 100644 index 000000000..62e39e509 --- /dev/null +++ b/tests/Reactor.Tests/Tooling/SearchIndexPlaceholderTests.cs @@ -0,0 +1,162 @@ +using System.Text.Json; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.UI.Reactor.SearchIndex; +using Xunit; + +namespace Microsoft.UI.Reactor.Tests.Tooling; + +public sealed class SearchIndexPlaceholderTests +{ + [Theory] + [InlineData("// Pick a colour, ... then bind\nAlpha();")] + [InlineData("// see Dsl.cs (...)\nAlpha();")] + [InlineData("Alpha(); // see Dsl.cs (...)")] + [InlineData("/* Pick a colour, ... then bind */\nAlpha();")] + [InlineData("/// see Dsl.cs (...)\nAlpha();")] + [InlineData("// Configure <your-key> or see .../docs\nAlpha();")] + [InlineData("TextBlock(\"Loading, ...\");")] + [InlineData("TextBlock(\"Please wait (...)\");")] + [InlineData("TextBlock(\"Type here...\");")] + [InlineData("TextBlock(@\"Loading, ...\");")] + [InlineData("TextBlock(\"\"\"Loading, ...\"\"\");")] + [InlineData("TextBlock(\"\"\"\nLoading, ...\n\"\"\");")] + [InlineData("TextBlock($\"Loading, ... {state}\");")] + [InlineData("TextBlock($@\"Loading, ... {state}\");")] + [InlineData("TextBlock($\"\"\"Loading, ... {state}\"\"\");")] + [InlineData("TextBlock($\"{state:(...)}\");")] + [InlineData("var text = \"Loading, ...\"u8;")] + [InlineData("var text = \"\"\"Loading, ...\"\"\"u8;")] + [InlineData("TextBlock(\"https://example.com/path // Loading, ...\");")] + [InlineData("TextBlock(\"Continue.../stop\");")] + [InlineData("TextBlock(\"Scanning /...\");")] + [InlineData("TextBlock(\"Example: https://example.com/media/( ... )\");")] + [InlineData("TextBlock(\"Show <your.azure.maps.key> in the help panel\");")] + [InlineData("var label = \"Scanning /...\"; TextBlock(label);")] + [InlineData("TextBlock(\"Show the tag <yourself>\");")] + [InlineData("Button(\"Run\").Click(() => { /* No-op: see Run(...) for the real command. */ });")] + [InlineData("var options = [.. otherOptions];")] + [InlineData("var items = new List<yourType>();")] + [InlineData("var items = new List<your_api_key>();")] + [InlineData("new Uri(\"https://example.com/docs?q=/...\");")] + [InlineData("new Uri(\"https://example.com/docs/page#archive/...\");")] + [InlineData("new Uri(\"https://example.com/docs/page\");")] + [InlineData("Image(\"ms-appx:///Assets/photos/photo.png\");")] + [InlineData("MediaPlayerElement(\"https://example.com/clip.mp4\");")] + [InlineData("TextBlock(\"https://example.com/photo.png\");")] + [InlineData("TextBlock(\"https://example.com/photo.png?caption=(...)#.../\");")] + [InlineData("TextBlock(\"Example: https://example.com/.../photo.png\");")] + [InlineData("TextBlock(\"Status: .../loading\");")] + [InlineData("TextBlock(\"Browse https://<your-host>/clip.mp4\");")] + [InlineData("TextBlock(\"1https://example.com/.../photo.png\");")] + [InlineData("TextBlock(\"https_demo://example.com/.../photo.png\");")] + [InlineData("MapControl(\"configured-key\");")] + [InlineData("Factories.MapControl(\"configured-key\");")] + [InlineData("MapControl(\"configured-key\", \"<your-note>\");")] + [InlineData("Factories.MapControl(\"configured-key\", \"<your-note>\");")] + [InlineData("new global::System.Uri(\"Assets/photo.png\", UriKind.Relative);")] + [InlineData("Factories . MapControl(\"configured-key\");")] + [InlineData("Factories /* maps */ . MapControl(\"configured-key\", \"<your-note>\");")] + [InlineData("new System /* note */ . Uri(\"Assets/photo.png\", UriKind.Relative);")] + [InlineData("new global /* alias */ :: System . Uri(\"Assets/photo.png\", UriKind.Relative);")] + [InlineData("Other /* note */ . MapControl(\"<your-key>\");")] + [InlineData("new Other /* note */ . Uri(\".../photo.png\", UriKind.Relative);")] + public void CompleteCards_WithProseEllipses_AreRetainedInSourceOrder(string code) + { + using var gallery = new MiniGallery(betaRouted: true); + gallery.OverwriteAlphaPage(PageWithCards(code)); + var editorial = gallery.WriteEditorial(Editorial); + + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorial).Json); + var samples = index.RootElement.GetProperty("controls")[0].GetProperty("samples"); + + // Pin both the leading card and a later card: a first-card-only gate misses later drops. + Assert.Equal(new[] { "First complete", "Unrelated", "Later complete" }, + samples.EnumerateArray().Select(s => s.GetProperty("header").GetString()).ToArray()); + Assert.Equal(code, samples[0].GetProperty("code").GetString()); + Assert.Equal(code, samples[2].GetProperty("code").GetString()); + } + + [Theory] + [InlineData("Alpha(a, ...);")] + [InlineData("Alpha(...);")] + [InlineData("Alpha(\n...\n);")] + [InlineData("Alpha(a, /* guidance */ ...);")] + [InlineData("Button(\"Run\").Click(...);")] + [InlineData("TextBlock($\"{Alpha(...)}\");")] + [InlineData("TextBlock($\"\"\"{Alpha(...)}\"\"\");")] + [InlineData("MapControl(\"<your-key>\");")] + [InlineData("MapControl(@\"<your-key>\");")] + [InlineData("MapControl(\"\"\"<your-key>\"\"\");")] + [InlineData("MapControl(\"<yourApiKey>\");")] + [InlineData("MapControl(<yourApiKey>);")] + [InlineData("MapControl(mapServiceToken: \"<your.azure.maps.key>\");")] + [InlineData("MapControl(\"<yourapikey>\");")] + [InlineData("Factories.MapControl(\"<your-key>\");")] + [InlineData("Factories.MapControl(mapServiceToken: \"<your-key>\");")] + [InlineData("new global::System.Uri(\".../photo.png\", UriKind.Relative);")] + [InlineData("new Uri(\"https://<your-host>/x\");")] + [InlineData("Factories . MapControl(\"<your-key>\");")] + [InlineData("Factories /* maps */ . MapControl(\"<your-key>\");")] + [InlineData("Factories . MapControl(mapServiceToken: \"<your-key>\");")] + [InlineData("new System . Uri(\".../photo.png\", UriKind.Relative);")] + [InlineData("new System /* note */ . Uri(\".../photo.png\", UriKind.Relative);")] + [InlineData("new global /* alias */ :: System /* note */ . Uri(\".../photo.png\", UriKind.Relative);")] + [InlineData("var uri = new Uri(\"ms-appx:///.../image.png\");")] + [InlineData("var uri = new Uri(\"https://example.com/media/(...)\");")] + [InlineData("var uri = new Uri(\"https://example.com/media/( ... )\");")] + [InlineData("var uri = new System.Uri(uriString: \"https://example.com/.../page\");")] + [InlineData("var uri = new Uri(\"https://example.com/docs/\", \".../page\");")] + [InlineData("Image(\"ms-appx:///Assets/.../photo.png\");")] + [InlineData("MediaPlayerElement(\"https://<your-host>/clip.mp4\");")] + [InlineData("TextBlock(\"https://example.com/.../photo.png\");")] + [InlineData("var source = \"https://example.com/.../photo.png\";")] + [InlineData("Image(@\"ms-appx:///Assets/.../photo.png\");")] + [InlineData("Image(\"\"\"ms-appx:///Assets/.../photo.png\"\"\");")] + [InlineData("var source = \"https://example.com/.../photo.png\"u8;")] + [InlineData("var source = \"\"\"https://example.com/.../photo.png\"\"\"u8;")] + [InlineData("HyperlinkButton(\"Open\", new(\"https://example.com/.../page\"));")] + [InlineData("Image(\"asset:.../photo.png\");")] + [InlineData("Image(\"APP+demo.v1-test://assets/.../photo.png\");")] + [InlineData("HyperlinkButton(\"Email\", \"mailto:<your-email>\");")] + [InlineData("Button(\"Run\").Click(() => { /* Do work, ... */ });")] + [InlineData("Button(\"Run\").Click(() => { /* ... omitted (...), fill in callback */ });")] + [InlineData("Alpha();\n// omitted: configure the handler\nBeta();")] + [InlineData("Button(\"Run\").Click(() => { /* ... */ });")] + [InlineData("Alpha();\n// ...\nBeta();")] + [InlineData("var data = ...;")] + [InlineData("var options = [ ... ];")] + [InlineData("Button(\"Run\").Click(() => { ... });")] + [InlineData("// Guidance only, ...")] + [InlineData("/* Guidance only, ... */")] + [InlineData("// omitted: replace the token\nvar token = \"<your-key>\"; MapControl(token);")] + public void AbbreviatedOrCommentOnlyCards_AreSkipped(string code) + { + using var gallery = new MiniGallery(betaRouted: true); + gallery.OverwriteAlphaPage(PageWithCards(code)); + var editorial = gallery.WriteEditorial(Editorial); + + using var index = JsonDocument.Parse(SearchIndexGenerator.Generate(gallery.GalleryDir, editorial).Json); + var samples = index.RootElement.GetProperty("controls")[0].GetProperty("samples"); + + Assert.Equal("Unrelated", Assert.Single(samples.EnumerateArray()).GetProperty("header").GetString()); + } + + const string Editorial = """ + { "alpha": { "keywords": ["alpha", "probe", "sample"] }, + "beta": { "keywords": ["beta", "probe", "sample"] } } + """; + + static string PageWithCards(string code) + { + var literal = SyntaxFactory.Literal(code).Text; + return $$""" + class AlphaPage + { + object Render() => VStack( + SampleCard("First complete", null, {{literal}}), + SampleCard("Unrelated", null, "Alpha();"), + SampleCard("Later complete", null, {{literal}})); + } + """; + } +} diff --git a/tools/Reactor.SearchIndex/README.md b/tools/Reactor.SearchIndex/README.md index 1f06184b2..1e95e0fb1 100644 --- a/tools/Reactor.SearchIndex/README.md +++ b/tools/Reactor.SearchIndex/README.md @@ -52,9 +52,20 @@ rewritten to absolute GitHub URLs, because the prose is read far from the file i - **Keywords are required** and canonicalized (trim / lowercase / collapse / dedupe) — generation fails if an included control has none. `curatedKeywords` (the consumer's higher-weighted 5.0 BM25 slot) is optional and canonicalized the same way. -- **Real code only** — sample cards with placeholder tokens (`...`, `<your-key>`, abbreviated - URLs) are rejected. Every *other* clean card on the page is emitted, in source order, with - case-insensitively duplicate headers dropped. +- **Real code only** — comment-only cards, code ellipses, and explicit comment elisions are + rejected. Mark omitted implementation with `// ...` or `// omitted: reason`. Legacy elision + comments beginning with `...` or ending with `, ...` are also recognized in empty blocks. + Ordinary comments and display text can contain ellipses. String literals starting with a + URI scheme are checked for `<your-key>` fill-ins and abbreviated path segments such as + `/.../` or `/( ... )`, wherever the literal appears. This includes URI templates displayed + by `TextBlock`. A scheme starts with an ASCII letter, contains letters, digits, `+`, `-`, + or `.`, and ends with `:` immediately followed by a non-whitespace character. Prose such + as `Example: https://...` is treated as display text. URI query and fragment text can + contain ellipses. Direct `MapControl` / `Factories.MapControl` token arguments also reject + fill-ins, and explicit `Uri` / `System.Uri` construction also checks relative paths. + For relative paths in other calls or placeholders assembled from variables and + interpolation, mark the omission explicitly with `// omitted: reason`. + Clean cards are emitted in source order, with case-insensitively duplicate headers dropped. - **No silent drops** — an orphan/typo'd editorial key, a misspelled editorial field, an unparseable `ControlInfo` entry, a `docs` entry missing its title or uri, an unclosed / nested / mismatched `<!-- index:… -->` marker, a marker id naming no control, a repo-relative link in a @@ -69,6 +80,14 @@ byte-equality with the committed file (the staleness gate that runs in CI `dotne `SearchIndexSkillParityTests.cs` requires every API a marked skill block demonstrates to appear in one of that entry's emitted samples. +`SearchIndexCoverageTests.cs` independently enumerates registry routes and their source cards, +then checks that their headers appear in the index in source order. Its manifest records each +deliberate omission with a reason. Editorial override headers come directly from `editorial.json` +and apply to the first non-skipped card, or provide a standalone sample header. Remove an omission +entry when its card becomes a complete sample. This check derives expected cards from source +without calling the generator's placeholder predicate, so refreshing an incomplete index still +fails coverage. + Curate `editorial.json` and the SKILL.md markers, never the generated JSON. ## Trimming / NativeAOT diff --git a/tools/Reactor.SearchIndex/SampleCode.cs b/tools/Reactor.SearchIndex/SampleCode.cs new file mode 100644 index 000000000..b64252773 --- /dev/null +++ b/tools/Reactor.SearchIndex/SampleCode.cs @@ -0,0 +1,128 @@ +using System.Text.RegularExpressions; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.CSharp.Syntax; + +namespace Microsoft.UI.Reactor.SearchIndex; + +static partial class SampleCode +{ + public static bool IsComplete(string code) + { + var root = CSharpSyntaxTree.ParseText(code).GetRoot(); + return root.DescendantTokens().Any(t => !t.IsMissing && !t.IsKind(SyntaxKind.EndOfFileToken)) + && !HasPlaceholder(code, root); + } + + static bool HasPlaceholder(string code, SyntaxNode root) + { + var codeOnly = code.ToCharArray(); + foreach (var trivia in root.DescendantTrivia()) + { + if (IsOrdinaryComment(trivia)) + { + var text = CommentText(trivia); + if (text == "..." || text.StartsWith("omitted:", StringComparison.OrdinalIgnoreCase)) + return true; + } + else if (!trivia.IsDirective && trivia.Kind() is not (SyntaxKind.DisabledTextTrivia + or SyntaxKind.SingleLineDocumentationCommentTrivia or SyntaxKind.MultiLineDocumentationCommentTrivia)) + { + continue; + } + + Mask(codeOnly, trivia.SpanStart, trivia.Span.Length); + } + + // Preserve legacy callback elisions without treating every prose ellipsis as incomplete. + foreach (var block in root.DescendantNodes().OfType<BlockSyntax>().Where(b => b.Statements.Count == 0)) + { + if (block.OpenBraceToken.TrailingTrivia.Concat(block.CloseBraceToken.LeadingTrivia) + .Any(t => IsOrdinaryComment(t) && CommentElision().IsMatch(CommentText(t)))) + return true; + } + + // Include skipped tokens during parser recovery. Mask only the text of interpolation, + // leaving the expressions inside its braces visible. A generic type argument is + // another legitimate use of angle brackets, even if the type name starts with 'your'. + foreach (var token in root.DescendantTokens(descendIntoTrivia: true)) + { + // URI-shaped literals carry the same placeholder policy in every call or assignment. + var value = token.ValueText; + if (token.Parent is LiteralExpressionSyntax && UriScheme().IsMatch(value) + && (ConfigurationPlaceholder().IsMatch(value) || HasAbbreviatedUriPath(value))) + return true; + + if (IsTextToken(token) || (token.IsKind(SyntaxKind.LessThanToken) && token.Parent is TypeArgumentListSyntax)) + Mask(codeOnly, token.SpanStart, token.Span.Length); + } + + var remaining = new string(codeOnly); + if (remaining.Contains("...", StringComparison.Ordinal) || ConfigurationPlaceholder().IsMatch(remaining)) + return true; + + return root.DescendantNodes().OfType<ArgumentSyntax>().Any(HasDirectPlaceholder); + } + + // Map-token fill-ins and relative URI paths still need these explicit syntax positions. + static bool HasDirectPlaceholder(ArgumentSyntax argument) + { + if (argument.Expression is not LiteralExpressionSyntax literal || !literal.IsKind(SyntaxKind.StringLiteralExpression) + || argument.Parent is not ArgumentListSyntax list) + return false; + + var uri = list.Parent is ObjectCreationExpressionSyntax creation + && NameText(creation.Type) is "Uri" or "System.Uri" or "global::System.Uri"; + var mapToken = list.Parent is InvocationExpressionSyntax call + && NameText(call.Expression) is "MapControl" or "Factories.MapControl" + && (argument.NameColon is { } named + ? named.Name.Identifier.ValueText == "mapServiceToken" + : list.Arguments.IndexOf(argument) == 0); + if (!uri && !mapToken) return false; + + var value = literal.Token.ValueText; + if (ConfigurationPlaceholder().IsMatch(value)) return true; + return uri && HasAbbreviatedUriPath(value); + } + + static string NameText(SyntaxNode name) => + string.Concat(name.DescendantTokens().Select(token => token.ValueText)); + + static bool HasAbbreviatedUriPath(string value) + { + var path = value.AsSpan(UriScheme().Match(value).Length); + var pathEnd = path.IndexOfAny('?', '#'); + return AbbreviatedPath().IsMatch(pathEnd < 0 ? path : path[..pathEnd]); + } + + static bool IsTextToken(SyntaxToken token) => token.Kind() is + SyntaxKind.StringLiteralToken or SyntaxKind.Utf8StringLiteralToken + or SyntaxKind.SingleLineRawStringLiteralToken or SyntaxKind.MultiLineRawStringLiteralToken + or SyntaxKind.Utf8SingleLineRawStringLiteralToken or SyntaxKind.Utf8MultiLineRawStringLiteralToken + or SyntaxKind.InterpolatedStringTextToken or SyntaxKind.CharacterLiteralToken; + + static bool IsOrdinaryComment(SyntaxTrivia trivia) => + trivia.Kind() is SyntaxKind.SingleLineCommentTrivia or SyntaxKind.MultiLineCommentTrivia; + + static string CommentText(SyntaxTrivia trivia) + { + var text = trivia.ToString()[2..]; + if (trivia.IsKind(SyntaxKind.MultiLineCommentTrivia) && text.EndsWith("*/", StringComparison.Ordinal)) + text = text[..^2]; + return text.Trim(); + } + + static void Mask(char[] code, int start, int length) => Array.Fill(code, ' ', start, length); + + [GeneratedRegex(@"^\.\.\.(?:\s|$)|,\s*\.\.\.$")] + private static partial Regex CommentElision(); + + [GeneratedRegex(@"<your[\w .-]+>")] + private static partial Regex ConfigurationPlaceholder(); + + [GeneratedRegex(@"^[A-Za-z][A-Za-z0-9+.-]*:(?=\S)")] + private static partial Regex UriScheme(); + + [GeneratedRegex(@"(?:^|[/\\])(?:\.\.\.|\([ \t]*\.\.\.[ \t]*\))(?=$|[/\\])")] + private static partial Regex AbbreviatedPath(); +} diff --git a/tools/Reactor.SearchIndex/SearchIndexGenerator.cs b/tools/Reactor.SearchIndex/SearchIndexGenerator.cs index 2e4802024..c97e4833e 100644 --- a/tools/Reactor.SearchIndex/SearchIndexGenerator.cs +++ b/tools/Reactor.SearchIndex/SearchIndexGenerator.cs @@ -318,7 +318,7 @@ static IReadOnlyList<ExtractedSample> QualifyingSamples(ClassDeclarationSyntax c if (header is null || code is null) continue; var normalized = NormalizeCode(code); - if (!HasRealCode(normalized) || HasPlaceholder(normalized)) continue; + if (!SampleCode.IsComplete(normalized)) continue; // Headers are the 0.8-weighted BM25 field and the human label for a hit, so two // cards sharing one header would emit an ambiguous duplicate. Keep the first. @@ -363,27 +363,6 @@ static IReadOnlyList<ExtractedSample> QualifyingSamples(ClassDeclarationSyntax c static string NormalizeCode(string code) => code.Replace("\r\n", "\n").Replace("\r", "\n").Trim(); - - // A snippet qualifies as a real code sample only if it has at least one line that - // isn't blank or a pure `//` comment — so a guidance card whose "sourceCode" is only - // a descriptive comment (e.g. SpacingPage's first card) is passed over for the next. - static bool HasRealCode(string code) => - code.Split('\n').Any(line => - { - var t = line.Trim(); - return t.Length > 0 && !t.StartsWith("//", StringComparison.Ordinal); - }); - - // Rejects a snippet that abbreviates required code with a placeholder — an args/element - // ellipsis ("x, ..." / "(...)" / "...)" / a lone "..." line) or an angle-bracket fill-in - // like <your-key>. Ellipses inside UI strings ("Type here...") are NOT matched, so those - // snippets still qualify. Enforces the REAL-CODE-ONLY invariant: the first *complete* - // card wins, and a control with no complete card needs an editorial sampleOverride. - [GeneratedRegex(@",\s*\.\.\.|\.\.\.\s*\)|\(\s*\.\.\.|^\s*\.\.\.\s*$|\.\.\./|<your", RegexOptions.Multiline)] - private static partial Regex PlaceholderRegex(); - - static bool HasPlaceholder(string code) => PlaceholderRegex().IsMatch(code); - [GeneratedRegex(@"\s+")] private static partial Regex WhitespaceRegex();