feat(cli): add React-aware symbol search

[aidenybai]

Why

Developers and coding agents need a deterministic way to find reusable JavaScript, TypeScript, and React symbols before adding duplicate code. Before this change, React Doctor's contributor workflows shell out to a separate Truffler CLI and have no React-specific component or hook vocabulary.

After this change, react-doctor find provides that workflow directly, with search and grep aliases, generic declaration kinds, React-aware component and hook kinds, grep-friendly text, and structured JSON.

Product brief

• Job: help developers and agents locate existing code before implementing overlapping helpers, components, hooks, or types.
• Change: add one standalone symbol-search command without changing scan defaults or report schemas.
• Reuse: use Truffler's Oxc scanner and fuzzy ranker internally, extended with React naming and wrapper conventions informed by Calldiff.
• Metric: reuse cli.invoked with command=find; success is at least 100 invocations across the next two releases.
• Compat: additive CLI surface, unchanged scan behavior and JSON report, with a patch changeset.
• Kill: reconsider or remove the command if it remains below 100 invocations after two releases.

What changed

• added find <query> [directory] with search and grep aliases
• added generic JS/TS kind filters plus React component, HOC, styled-component, and hook classification
• added behavior-phrase normalization, result limits, path validation, JSON output, and parse-error recovery
• bundled the symbol-search implementation and declared its parser runtime dependency for packed installs
• replaced direct Truffler CLI instructions in AGENTS.md and the contributor skills with react-doctor find
• documented the command, added adoption telemetry, regression coverage, and a patch changeset

RDE/parity was not run because this is an additive CLI workflow, not a lint rule or detector change.

Test plan

• nr typecheck — passed across all 11 workspace packages
• nr lint — passed with existing fuzz-corpus warnings only
• nr format:check — passed
• nr test in packages/react-doctor — 2,438 passed, 27 skipped
• focused find/flag tests — 31 passed
• production CLI build plus real find, search, and grep fixture smoke tests — passed
• nr smoke:packed-cli-install — passed with no forbidden packages
• full workspace nr test was attempted; five unrelated eval suites could not import Daytona's undeclared tslib dependency, while the 127 eval tests that loaded passed

---

Note

Low Risk
Additive CLI and documentation only; scan/report behavior is unchanged, with tests and smoke coverage for the new command.

Overview
Introduces react-doctor find <query> [directory] (aliases search, grep) as an additive CLI for fuzzy JavaScript/TypeScript symbol lookup—grep-friendly lines or --json, --kind filters (including React component and hook), limits, path validation, and parse-error warnings. Search is implemented via @rayhanadev/truffler (bundled for packed installs), with local helpers for kind parsing, React naming/wrapper classification, and output formatting; adoption is tracked on cli.invoked with command=find.

Truffler moves from a root devDependency to a react-doctor runtime dependency (plus oxc-parser); root package.json drops the standalone Truffler dev dep. AGENTS.md, contributor skills, and the agent skill now tell people to run react-doctor find instead of bunx @rayhanadev/truffler. README documents the command; a patch changeset ships the new surface.

^{Reviewed by Cursor Bugbot for commit 825b6da. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/eslint-plugin-react-doctor@1627

npm i https://pkg.pr.new/oxlint-plugin-react-doctor@1627

npm i https://pkg.pr.new/react-doctor@1627

commit: 825b6da

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit 825b6da.}

[github-actions]

Interactive terminal E2E

Terminal Control verified the built CLI at 825b6da in a real PTY:

• selected a project interactively and observed Scanning... before the three-second Git delay completed
• waited for the clean result and exercised the compact report
• opened copy context and the GitHub Actions confirmation, then cancelled safely

Download the edited MP4 and PNG evidence

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2e5fb02. Configure here.}