Repository navigation
find-ui: search control descriptions and add an API list to the sample index - #1048
Conversation
SearchEngine built its control BM25 document from the control name, id,
camel-split name, curated keywords, enrichment tags, and scenario headers.
ControlDescription was read only to populate the display field, never indexed,
so it was visible in results but invisible to search. Core patterns already
indexed their Description, so the two halves of the same engine disagreed.
That description is the only control field carrying task vocabulary - what a
control is for, rather than what it is called. Without it an intent query could
not reach its control even when the description was a near-verbatim paraphrase
of the query:
find-ui "floatable" -> no matches, though "floatable" is in Docking's
description
find-ui "tearable" -> no matches, though "tearable" is in Docking's
description
Add ControlConceptText as a weighted field to both document builders (Search
and SearchGrouped), resolved the same way the display path already resolves it:
the explicit toolkit frontmatter ControlDescription first, then the per-control
Description that Gallery repeats on every scenario row.
The weight of 1.5 matches the scenario-header field and is deliberately
conservative - it is not tuned. Tuning it, and the 70% runner-up floor that can
still suppress a description-only match, both change every query, so they are
left for a measured evaluation rather than set by spot checks.
Both new tests fail without this change and pass with it.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a336c3b2-7884-416a-b845-524651f59a49
The index models which control a sample demonstrates but not which APIs it calls, so a source that knows its own API references has nowhere to put them and they are dropped at ingest. Add an optional apis[] to both control and sample, following the existing control-default / sample-override pattern. Spelled uri rather than url to match docLink, so one document does not carry two spellings of the concept. Scenario.Apis is nullable and omitted when null: a corpus where no source populates it stays byte-identical to one baked before the field existed, so this needs no cache version bump and no re-bake. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 415c898a-0d29-4429-b6f8-e6428d685e5c
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2ba26bd4-1f3b-4e45-9ede-d3065cbaf57b
There was a problem hiding this comment.
🟢 Approval recommended
Release build, NativeAOT publish, and all 185 targeted tests passed; only a non-blocking sanitizer-test gap remains.
1 open finding
What changed in this PR
Adds description-aware find-ui ranking and API metadata support to the sample-index contract.
Changes:
- Indexes control descriptions for intent-based searches.
- Parses, sanitizes, caches, and round-trips optional API references.
- Adds schema and search regression coverage.
| File | Description |
|---|---|
SearchEngine.cs |
Adds descriptions to BM25 scoring. |
ScenarioSanitizer.cs |
Sanitizes API metadata. |
SampleIndexSchema.cs |
Declares API fields. |
SampleIndexParser.cs |
Parses inherited or sample-specific APIs. |
Models.cs |
Adds the ApiRef model. |
SampleIndexTests.cs |
Tests API round trips and schema alignment. |
FindUiSearchTests.cs |
Tests description-only searches. |
SampleIndexWriter.cs |
Writes shared or per-sample APIs. |
winui-sample-index.schema.json |
Documents the API-list contract. |
🧠 Review effort: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2ba26bd4-1f3b-4e45-9ede-d3065cbaf57b
Build Metrics ReportValidation passed. All required build and validation jobs succeeded. Binary Sizes
.NET Test Results (TRX reports)Other suites are reflected in the overall validation status above. ✅ 8335 passed, 37 skipped out of 8372 tests in 1225.0s (+4 tests, +53.0s vs. baseline) Test Coverage✅ 87.6% line coverage, 82.4% branch coverage · ✅ no change vs. baseline CLI Startup Time63ms median (x64, Try This BuildInstalls the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing. & ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 1048Switching between builds often?Put the tool on your PATH once: & ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPathThen this build is just: winapp-pr 1048Run Updated 2026-10-12 12:52:44 UTC · commit |
Zach Teutsch (zateutsch)
left a comment
There was a problem hiding this comment.
🤖 AI-generated review (winappcli pr-review skill) — verify before acting.
Decision: looks good to merge. Nothing blocking.
What I checked:
dotnet build src/winapp-CLI/winapp.sln -c Debug: built with 0 warnings and 0 errors.- Tests matching
FindUi,SampleIndex,ScenarioSanitizer,EmbeddedSnapshotandControlsSearchService: all 179 passed. winapp find-ui "show data in tabular rows and columns" --jsonwith the built binary: TableView ranked first, then ListView, matching the table in the description.winapp find-ui button --json: the output has noapiskey.
Not checked: I didn't serve a hostile sample index (escape codes or newlines in the apis fields) to the CLI. The sanitizer unit tests cover that path, and nothing uses uri yet.
I left one optional inline comment.
…iption Resolve conflicts with main's Toolkit index work (#988): keep both the description BM25 field and header CamelCase expansion, both the Apis and Toolkit schema properties, and both the API and usings sanitizers. Address review: add 'apis' to the schema's top-level summary of fields added beyond the Reactor shape. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 43bc5058-580c-4a12-a4f8-820bc6a842e6

Description
Two small improvements to
winapp find-uiand the sample index it reads.1. Search now matches a control's description. Before this change, keyword search only looked at a control's name, keywords, tags and sample headers. The description is the only field that says what a control is for, so searches that described a task rarely reached the right control.
2. The sample index can list the APIs a sample uses. Each control or individual sample can now include an optional
apislist (nameis required;descriptionanduriare optional). Use it on the control when all of its samples call the same APIs, or on a sample when they differ. This lets sample sources such as windows-samples publish which APIs each sample calls.find-uireads the list but doesn't display or search it yet.No current source publishes
apis, so the cached corpus is unchanged and no cache invalidation is needed.Usage Example
Results from
winapp find-ui "<query>" --jsononmainand on this branch:maintop resultsshow data in tabular rows and columnstheme aware container with rounded cornersbuttonExact control-name searches return the same top result as on
main.Example
apisentry in a sample index:Related Issue
Related to #625 and #703.
Type of Change
Checklist
Screenshots / Demo
N/A (no visual change). The CLI output is shown in the table above.
Additional Notes
Validation was run on this branch merged with the latest
main:dotnet test src\winapp-CLI\WinApp.Cli.Tests\WinApp.Cli.Tests.csproj --filter "FullyQualifiedName~FindUi|FullyQualifiedName~SampleIndex|FullyQualifiedName~EmbeddedSnapshot|FullyQualifiedName~ControlsSearchService|FullyQualifiedName~ControlsFetchNotice|FullyQualifiedName~ScenarioSanitizer": 185 of 185 tests passed.find-uionmainand on this branch with 80 single-name and 25 two-word control-name queries: every top result was unchanged.Why this PR has the
corpus-rebake-not-neededlabel: I baked the corpus withmainand with this branch, usingdotnet run --project src/winapp-CLI/WinApp.Cli.SnapshotBaker -- <dir>against the same upstream data.snapshot-gallery,snapshot-reactorandsnapshot-toolkitwere byte-identical.snapshot-manifest.jsondiffered only in itsbakedAtUtctimestamp.When a source starts publishing
apis, re-bake the corpus and bumpCacheVersionin that change so existing caches pick up the new field.