feat(react-x): add additionalMutableHooks setting, closes #1924

[christopher-buss]

What kind of change does this PR introduce?

• Feature

Adds an additionalMutableHooks shared setting, as proposed in #1924: a regex matching custom hooks that return external mutable stores. Writes through values initialized by such a hook are exempted by react-x/immutability, the same way values returned by the built-in navigation hooks already are.

{
  "settings": {
    "react-x": {
      "additionalMutableHooks": "/^(useWorld|useMyStore)$/u"
    }
  }
}

// no longer reported with the setting above
function Component() {
  const world = useWorld();
  const onClose = useCallback(() => {
    world.set({ open: false });
  }, [world]);
  return <AnotherComponent onClose={onClose} />;
}

Registering such a hook under additionalRefHooks works today, but it declares the value a ref, so react-naming-convention/ref-name then asks for it to be renamed — the misdeclaration leaks into other rules.

Implementation notes

• packages/shared/src/settings.ts: additionalMutableHooks follows the existing additional*Hooks shape (schema, normalized interface, toRegExp).
• immutability/lib.ts: isKnownNonMutatingMethodCall becomes isInitializedFromMutableHook. Both the built-in NAVIGATION_HOOKS and the configured pattern are matched on the callee name from Extract.getCalleeName, which is how isUseRefLikeCall and the other isUse*LikeCall predicates match. isAPI is name-shaped too, so this is not a behaviour change; it removes the second matching mechanism from one function.
• immutability/effects.ts: the exemption applies to every write through the value (store.count = 1, delete store.stale), not only to mutating method calls. This widens the existing navigation-hook exemption. The reason for the exemption is a property of the value — it is not a captured local — so it does not depend on the write syntax, and the useRef exemption is already syntax-uniform (ref.current = 1 and box.current.push(1) are both exempt). Reassignment of the binding itself (world = null) stays a mutation.
• immutability.spec.diff.md: the mutation table and the exception paragraph still described the exemption as method-call-only and listed three navigation hooks; useHistory landed in 5.16.1. Updated, with the destructuring boundary recorded. The Last verified stamp is left for you.

Provenance is per declaration, not per destructured element: const { store, actions } = useMyStore() exempts writes through actions as well. That looks right for a store hook, and there is now a valid test pinning it.

Open question

additionalRefHooks shipped with a core.isUseRefLikeCall predicate plus a RuleToolkit.is entry. I did not add a core predicate here, because it would move third-party hook names (useRouter, useNavigate, …) into packages/core, which today holds React built-ins only. Happy to add core.isUseMutableStoreLikeCall + the kit entry if you would rather keep the symmetry.

Does this PR introduce a breaking change?

• No

Checklist

• When resolving issues, they are referenced in the PR's title
• I have added a convincing reason for adding this feature, if necessary

Other information

Docs updated: rule immutability.mdx, configure-analyzer.mdx/.tsx, kit.mdx settings table, faq.mdx, rule CHANGELOG.md, plus regenerated typedoc output for @eslint-react/shared. Full test suite passes, including 4 new valid and 2 new invalid cases for the setting.

[vercel]

@christopher-buss is attempting to deploy a commit to the Rel1cx's projects Team on Vercel.

A member of the Team first needs to authorize it.