refactor(eslint-rules): split consistent-base-hook into base-hook-signature + base-hook-no-forbidden-runtime#36251
Draft
Hotell wants to merge 18 commits into
Draft
Conversation
Enforces the v9 base hook API contract for any function matching
`use<Name>Base_unstable`:
- 1 or 2 positional parameters; first must be named `props`,
optional second must be named `ref` and typed as `React.Ref<...>`.
- No references to bindings imported from configured forbidden
packages (defaults to `@fluentui/react-tabster`, `tabster`,
`keyborg`). Forbidden-package detection is scope-based, so
local shadowing is handled correctly.
Options:
{ forbiddenPackages?: Array<string | { name: string; allow?: string[] }> }
…legacy base hooks Pre-existing base hooks that don't yet conform to the new contract (missing/non-React.Ref-typed `ref` param, or references to tabster/keyborg bindings) are suppressed with line-scoped `eslint-disable-next-line` comments so the rule can ship as `error` for new code. Refactors to remove the suppressions will follow. Affected packages: - react-checkbox, react-menu, react-radio, react-rating, react-slider, react-switch, react-tags, react-tooltip
…e-hook `useFocusWithin` from `@fluentui/react-tabster` is a pure ref-attaching utility with no global side effects; it's safe to use inside base hooks. Added to the default allowlist so callers don't need to opt-out per-site.
…essions `useFocusWithin` is now part of the rule's default allowlist, so the line-scoped suppressions in react-checkbox, react-radio, react-rating, react-slider, and react-switch are no longer needed.
…se-hook Same rationale as `useFocusWithin`: `useFocusVisible` from `@fluentui/react-tabster` is safe to use inside base hooks.
…yborg from forbidden list
- Remove `keyborg` from the default forbidden packages list. Base hooks
may freely depend on `keyborg` since it carries no tabster runtime.
- Expand the default allowlist for `@fluentui/react-tabster` with APIs
that internally depend only on `keyborg` (no `tabster` runtime):
- useKeyboardNavAttribute
- useIsNavigatingWithKeyboard
- useSetKeyboardNavigation
- useOnKeyboardNavigationChange
- applyFocusVisiblePolyfill
- KEYBORG_FOCUSIN / KeyborgFocusInEvent (re-exports from `keyborg`)
…ions `useIsNavigatingWithKeyboard`, `KEYBORG_FOCUSIN`, and `KeyborgFocusInEvent` are now part of the rule's default allowlist.
… in consistent-base-hook
Replace the hand-curated allow/forbidden package lists with per-symbol transitive value-import analysis powered by typescript-eslint ParserServices and the TypeScript Program. The rule now traces each base-hook import back to its defining source file and walks non-type-only re-exports/imports to detect whether the symbol's module graph reaches any configured forbidden runtime package.
Options shape: { watchedPackages?: string[]; forbiddenRuntimes?: string[] }. Defaults: watchedPackages=['@fluentui/react-tabster'], forbiddenRuntimes=['tabster']. New message ids: forbiddenRuntimeDirect, forbiddenRuntimeReach. Type-only imports are skipped. When typed services are unavailable, only direct forbidden-runtime imports are reported.
By default (allowTypeImports: false) type-only imports from forbiddenRuntimes packages are disallowed inside base hooks, to keep the base hook's public API fully decoupled from those packages. Setting allowTypeImports: true restores the previous behavior of skipping type-only imports. Type-only imports from watched packages are unaffected (types cannot transitively pull runtime).
…nore fixtures from type check
…; fix tooltip directive - isReactRefTypeAnnotation now resolves the Ref/React identifier via scope analysis and requires it to be imported from 'react'. Adds tests for local aliases, non-react imports, and shadowed React.- useTooltipBase_unstable: use bare 'use no memo' directive prologue instead of parenthesized expression so React Compiler detects it.
…onsistent-base-hook
Extend the rule's transitive analysis so type references in a base hook
signature are also checked against forbidden runtimes when they originate
from a watched package whose defining module reaches a forbidden runtime
(via either value or type imports).
- Track type-only imports from watched packages (previously skipped).
- Per-Program cache now stores { value, all } reach sets, filled in a
single DFS pass so the new analysis adds no extra resolution work.
- visitScope picks the reach set based on reference.isTypeReference:
value refs use value reach (runtime coupling), type refs use all
reach (API-surface coupling).
- allowTypeImports is now symmetric: when true, type-only imports are
exempt from BOTH direct forbidden checks AND transitive watched
reach checks.
- New tests cover symmetric exemption, type-only watched -> clean
module (allowed), and indirect type leakage via HeavyWrapper whose
defining file value-re-exports the heavy module.
…k signature detection Wrapping state hooks (`use<X>_unstable`) that pair with a base hook (`use<X>Base_unstable`) must also follow the `(props, ref)` signature contract. Pair detection checks the same file first, then sibling files (`.ts`/`.tsx`) in the same directory. Suppress the violation on `useTagGroupBase_unstable`, which takes a third `options` argument used internally by `useTagGroup_unstable`.
…nature + base-hook-no-forbidden-runtime Replaces the single `@nx/workspace-consistent-base-hook` rule with two focused rules: - `@nx/workspace-base-hook-signature` (untyped) — enforces the API contract for base hooks: 1–2 positional parameters named `props` and optional `ref`, with `ref` typed as `React.Ref<...>`. Detects targets by name pattern (`use*Base_unstable`) OR by pair detection — when a `use<Name>_unstable` exists alongside a co-located or sibling-file `use<Name>Base_unstable`, the state hook is also validated. - `@nx/workspace-base-hook-no-forbidden-runtime` (type-aware) — enforces that base hooks do not transitively pull forbidden runtime packages (default `tabster`) directly or via configured watched packages (default `@fluentui/react-tabster`). Extracted shared utilities: - `utils/tracked-imports.ts` — import-specifier metadata and naming. - `utils/module-resolver.ts` — TS module resolution + bare-spec helpers. - `utils/transitive-reach.ts` — per-program cached value/all reach analysis with cycle handling. - `utils/base-hook-detector.ts` — name patterns, base/state pairing, same-file + sibling-file detection. Other changes: - `packages/eslint-plugin/src/internal.js` — register both new rules in place of the old one. - `packages/react-components/react-tags/.../useTagGroup.ts` — suppression comment updated to point at the new `base-hook-signature` rule name. - Fixture dir renamed `__fixtures__/consistent-base-hook/` → `__fixtures__/base-hook-no-forbidden-runtime/`. Signature fixture lives at `__fixtures__/base-hook-signature/`. Tests: 76/76 pass (5 suites). vNext lint sweep clean.
📊 Bundle size report
Unchanged fixtures
|
…idden-runtime The shared utilities split off in the previous commit were only consumed by `base-hook-no-forbidden-runtime`: - `utils/tracked-imports.ts` - `utils/transitive-reach.ts` - `utils/module-resolver.ts` Inline them back into the rule file so `utils/` only contains genuinely cross-rule helpers (currently `base-hook-detector.ts`, used by both the signature and runtime rules). Also drop the `export` keyword from `BASE_SUFFIX` / `UNSTABLE_SUFFIX` in `base-hook-detector.ts` — both are only consumed by the in-file `createPairDetector` factory.
|
Pull request demo site: URL |
…p utils/ Premature shared-utils abstraction: only two rules existed and the duplicated surface area is ~18 lines (BASE_HOOK_NAME_PATTERN, the BaseHookFunction type, getFunctionInit). Inlining makes each rule self-contained at the cost of trivial duplication. - Move all base-hook-detector exports into base-hook-signature.ts (signature rule owns the full pair-detection mechanism). - Duplicate BASE_HOOK_NAME_PATTERN / BaseHookFunction / getFunctionInit into base-hook-no-forbidden-runtime.ts. - Delete tools/eslint-rules/utils/ entirely.
This was referenced May 26, 2026
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| @@ -35,6 +35,8 @@ const __internal = { | |||
| /** @type {import('eslint').Linter.RulesRecord} */ | |||
There was a problem hiding this comment.
🕵🏾♀️ visual changes to review in the Visual Change Report
vr-tests-react-components/Charts-DonutChart 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-react-components/Charts-DonutChart.Dynamic.default.chromium.png | 5581 | Changed |
vr-tests-react-components/Menu Converged - submenuIndicator slotted content 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-react-components/Menu Converged - submenuIndicator slotted content.default.submenus open.chromium.png | 413 | Changed |
vr-tests-react-components/Positioning 2 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-react-components/Positioning.Positioning end.chromium.png | 629 | Changed |
| vr-tests-react-components/Positioning.Positioning end.updated 2 times.chromium.png | 742 | Changed |
vr-tests-react-components/ProgressBar converged 3 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-react-components/ProgressBar converged.Indeterminate + thickness - Dark Mode.default.chromium.png | 34 | Changed |
| vr-tests-react-components/ProgressBar converged.Indeterminate + thickness.default.chromium.png | 41 | Changed |
| vr-tests-react-components/ProgressBar converged.Indeterminate + thickness - High Contrast.default.chromium.png | 34 | Changed |
vr-tests-react-components/TagPicker 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-react-components/TagPicker.disabled - High Contrast.chromium.png | 1319 | Changed |
vr-tests-web-components/Avatar 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-web-components/Avatar. - Dark Mode.normal.chromium.png | 10380 | Changed |
vr-tests-web-components/RadioGroup 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests-web-components/RadioGroup. - Dark Mode.1st selected.chromium_2.png | 119 | Changed |
vr-tests/Callout 2 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests/Callout.No callout width specified.default.chromium.png | 2143 | Changed |
| vr-tests/Callout.Root.default.chromium.png | 2195 | Changed |
vr-tests/react-charting-LineChart 1 screenshots
| Image Name | Diff(in Pixels) | Image Type |
|---|---|---|
| vr-tests/react-charting-LineChart.Multiple - RTL.default.chromium.png | 200 | Changed |
There were 1 duplicate changes discarded. Check the build logs for more information.
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
1 participant
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.
Summary
Splits the monolithic
@nx/workspace-consistent-base-hookESLint rule (introduced in #36236) into two focused rules, extracts shared utilities, and extends signature enforcement to paired state hooks via pair detection.Rules after split
1.
@nx/workspace-base-hook-signature(untyped)Enforces the API contract for base hooks and their paired state hooks:
propsand optionalrefreftyped asReact.Ref<...>Detection strategy — Option C, pair-based:
use<Name>Base_unstableuse<Name>_unstableis also validated when a siblinguse<Name>Base_unstableexists either in the same file or in a sibling file in the same component folder (covers Tooltip/Field/MenuItem-style outliers).2.
@nx/workspace-base-hook-no-forbidden-runtime(type-aware)Enforces that base hooks do not transitively pull forbidden runtime packages (default:
tabster) — directly or via configured watched packages (default:@fluentui/react-tabster). Behavior unchanged from PR #36236; only the rule name changed and the signature concerns moved out.Shared utilities
Extracted from the original rule for reuse and testability:
utils/tracked-imports.ts— import-specifier metadata + namingutils/module-resolver.ts— TS module resolution + bare-spec helpersutils/transitive-reach.ts— per-ts.Programcached value/all reach analysis with cycle handlingutils/base-hook-detector.ts— name patterns + same-file/sibling-file base↔state pair detectionOther changes
packages/eslint-plugin/src/internal.js— register both new rules in place of the old onepackages/react-components/react-tags/.../useTagGroup.ts— suppression comment renamed to point atbase-hook-signature__fixtures__/consistent-base-hook/renamed →__fixtures__/base-hook-no-forbidden-runtime/; signature fixtures live under__fixtures__/base-hook-signature/Validation
nx run-many -t lint --projects=tag:vNextexits clean — no new violations introduced by the renameMigration
@nx/workspace-consistent-base-hook@nx/workspace-base-hook-signature+@nx/workspace-base-hook-no-forbidden-runtimewatchedPackages, etc.)use*Base_unstableuse*_unstablestate hooks