fix: doctor enrichers INFO + find multi-match diagnostic#22
Merged
Conversation
…match diagnostic Enrichers are opt-in, so zero registered is a valid state rather than a warning; dusk:doctor now emits INFO instead of WARN (#9). dusk:find detects when a semantics label matches more than one node and returns a diagnostic so agents can disambiguate with --text/--contains or a q-handle, while still resolving the first match (#15, #16). Adds skill and doc guidance on e-ref staleness versus q-handles.
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR reduces false alarms in dusk:doctor by downgrading the “no enrichers registered” check from WARN to INFO (since enrichers are opt-in), and improves ext.dusk.find by surfacing ambiguity when --semanticsLabel / --text match multiple semantics nodes via matchCount plus an optional diagnostic field. It also updates tests and agent-facing docs/skill guidance around multi-match disambiguation and e-ref staleness vs q-handles.
Changes:
dusk:doctorcheck 3 now emits INFO (not WARN) when zero enrichers are registered.ext.dusk.findnow returnsmatchCounton success and adds adiagnosticstring when ambiguous matches occur, while still returning the first match (backward compatible).- Tests, docs, skill, and changelog updated to reflect the new ambiguity diagnostic and ref-handling guidance.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| lib/src/commands/dusk_doctor_command.dart | Downgrades “no enrichers” output from WARN to INFO. |
| test/src/commands/dusk_doctor_command_test.dart | Updates doctor tests to expect INFO messaging for empty enrichers. |
| lib/src/extensions/ext_find.dart | Adds matchCount + optional diagnostic for multi-match label/text queries. |
| test/src/extensions/ext_find_test.dart | Adds widget tests asserting multi-match diagnostics and single-match behavior. |
| doc/commands/dusk-find.md | Documents matchCount and ambiguity diagnostics + disambiguation strategies. |
| skills/fluttersdk-dusk/SKILL.md | Adds guidance on e-ref staleness and --semanticsLabel over-match handling. |
| skills/fluttersdk-dusk/references/actionability-and-refs.md | Adds a dedicated section on semanticsLabel over-match + mitigation strategies. |
| CHANGELOG.md | Records the new ext.dusk.find fields and the doctor INFO change under Unreleased. |
…ng tearDown - Replace 'refine with --text/--contains or use a q-handle' with 'refine with --key, --text, or --contains' across all locations: ext_find.dart (both diagnostic builders), doc/commands/dusk-find.md (both example blocks), skills refs/actionability-and-refs.md (diagnostic example), and CHANGELOG.md ([Unreleased] entry). The old wording was self-contradictory: dusk:find already returns a q-handle, so 'use a q-handle' confused agents. The new wording focuses on predicate refinement and surfaces --key first (the most precise disambiguator). - Reword resolveQueryWithCount docstring to accurately describe matchCount semantics: 1 on a single match, 0 on no match (the old text claimed key/text-only paths 'always report 1', which contradicted the (null, 0, null) return on no-match). - Remove 'silently' from SKILL.md and actionability-and-refs.md: dusk:find no longer silently picks the first node on ambiguity; it now surfaces matchCount and diagnostic. - Add tearDown(RefRegistry.resetForTesting) to the multi-match test group in ext_find_test.dart to prevent q/e token state from leaking into later tests (repo test guideline requires both setUp and tearDown when RefRegistry state is touched).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes REPORT friction items #9, #15, #16.
dusk:doctoremits INFO instead of WARN when zero enrichers are registered (enrichers are opt-in; zero is a valid state, not an error next to "integration wired").dusk:finddetects when a semantics label matches more than one node and returns a diagnostic so agents can disambiguate with--text/--containsor a q-handle, while still resolving the first match (backward compatible). Adds skill + doc guidance on e-ref staleness vs q-handles.TDD. analyze 0, format 0-diff,
flutter test793 pass. Frozen contracts (RefRegistry, navigate typedef) untouched.