Skip to content

find-ui: search control descriptions and add an API list to the sample index - #1048

Merged
Nikola Metulev (nmetulev) merged 7 commits into
mainfrom
jay/find-ui-index-improvements
Oct 12, 2026
Merged

Nikola Metulev (nmetulev) merged 7 commits into
mainfrom
jay/find-ui-index-improvements

Conversation

@Jaylyn-Barbee

@Jaylyn-Barbee Jaylyn Barbee (Jaylyn-Barbee) commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Description

Two small improvements to winapp find-ui and 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 apis list (name is required; description and uri are 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-ui reads 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>" --json on main and on this branch:

Query main top results This branch top results
show data in tabular rows and columns ListView, TableView, Grid TableView, ListView
theme aware container with rounded corners StackPanel, Border, Grid Border, StackPanel, Grid
button Button Button

Exact control-name searches return the same top result as on main.

Example apis entry in a sample index:

"apis": [
  { "name": "Windows.Storage.Pickers.FileOpenPicker", "uri": "https://learn.microsoft.com/..." }
]

Related Issue

Related to #625 and #703.

Type of Change

  • ✨ New feature
  • 🧪 Test update

Checklist

  • New tests added for new functionality (if applicable)
  • Tested locally on Windows

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.
  • Ran find-ui on main and 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-needed label: I baked the corpus with main and with this branch, using dotnet run --project src/winapp-CLI/WinApp.Cli.SnapshotBaker -- <dir> against the same upstream data. snapshot-gallery, snapshot-reactor and snapshot-toolkit were byte-identical. snapshot-manifest.json differed only in its bakedAtUtc timestamp.

When a source starts publishing apis, re-bake the corpus and bump CacheVersion in that change so existing caches pick up the new field.

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
Copilot AI balanced review requested due to automatic review settings October 9, 2026 16:42
@Jaylyn-Barbee Jaylyn Barbee (Jaylyn-Barbee) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Oct 9, 2026
@Jaylyn-Barbee Jaylyn Barbee (Jaylyn-Barbee) added the corpus-rebake-not-needed find-ui corpus freshness check: this PR's changes provably do not alter what a bake produces label Oct 9, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2ba26bd4-1f3b-4e45-9ede-d3065cbaf57b

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact Baseline Current Delta
CLI (ARM64) 57.77 MB 57.80 MB 📈 +23.5 KB (+0.04%)
CLI (x64) 57.79 MB 57.82 MB 📈 +23.5 KB (+0.04%)
MSIX (ARM64) 24.02 MB 24.03 MB 📈 +11.5 KB (+0.05%)
MSIX (x64) 25.49 MB 25.51 MB 📈 +16.2 KB (+0.06%)
NPM Package 50.08 MB 50.10 MB 📈 +19.4 KB (+0.04%)
NuGet Package 50.19 MB 50.21 MB 📈 +16.7 KB (+0.03%)

.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 Time

63ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs 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))) 1048
Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 1048

Run winapp-pr with no arguments to pick from a list of open PRs.


Updated 2026-10-12 12:52:44 UTC · commit 3421c7e · workflow run

@Jaylyn-Barbee Jaylyn Barbee (Jaylyn-Barbee) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 9, 2026

@zateutsch Zach Teutsch (zateutsch) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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, EmbeddedSnapshot and ControlsSearchService: all 179 passed.
  • winapp find-ui "show data in tabular rows and columns" --json with the built binary: TableView ranked first, then ListView, matching the table in the description.
  • winapp find-ui button --json: the output has no apis key.

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.

Comment thread docs/winui-sample-index.schema.json Resolved
…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
@Jaylyn-Barbee Jaylyn Barbee (Jaylyn-Barbee) added agent-preparing Agent is addressing feedback or completing required validation and CI ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 12, 2026
@nmetulev
Nikola Metulev (nmetulev) merged commit 7e057a4 into main Oct 12, 2026
13 checks passed
@nmetulev
Nikola Metulev (nmetulev) deleted the jay/find-ui-index-improvements branch October 12, 2026 19:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

corpus-rebake-not-needed find-ui corpus freshness check: this PR's changes provably do not alter what a bake produces ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants