@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/providerWraps.ts

@@ -0,0 +1,1977 @@
+/**
+ * Context providers the mount planes cannot see.
+ *
+ * A component under a real layout mounts inside SidebarProvider, InfobarProvider,
+ * whatever — but the sweeps analyse COMPONENTS (src/components/**), and the
+ * layout that supplies the context is a route file outside the entry glob. The
+ * kiranism dogfood: every Sidebar* and Infobar* mount failed with "useSidebar
+ * must be used within a SidebarProvider" because nothing in the analysed tree
+ * had ever imported SidebarProvider — only app/dashboard/layout.tsx does.
+ *
+ * Three derivations, strongest evidence first:
+ *
+ * 1. HOOK CALL. A component that CALLS useX needs XProvider mounted. Same-file
+ *    call → the provider lives in the component's own file; cross-file call →
+ *    the hook's import resolves to the provider's file, and only that file's
+ *    provider counts, so an unrelated FooProvider elsewhere never wraps an
+ *    unrelated useFoo caller.
+ *
+ * 2. NAMESPACE COMPOUND. shadcn primitives wrap a third-party namespace
+ *    (cmdk, base-ui): CommandInput renders <CommandPrimitive.Input> and throws
+ *    on undefined store context unless <Command> — the same file's bare
+ *    <CommandPrimitive> renderer, or its <ToastPrimitive.Provider> renderer —
+ *    is mounted around it.
+ *
+ * 3. TRANSITIVE REQUIREMENT. AppSidebar never calls useSidebar — its child
+ *    <Sidebar> does, and the error surfaces at AppSidebar's mount. Whatever a
+ *    component renders, it must also satisfy.
+ *
+ * A hand-off is invisible to all three: in a Feature-Sliced app the file a
+ * component imports is `export * from './model'`, so the hook it names, and the
+ * library that hook calls three files away, sit in a module the import never
+ * mentions. Derive follows the re-export table (see reexportTable) whenever the
+ * imported file does not declare the hook itself.
+ *
+ * The provider may be no analysed component at all (the layout-only case), so
+ * its file is PARSED here for the export shape — non-async and exported is the
+ * whole gate; a provider that cannot mount bare takes down the wraps it guards,
+ * and the dogfood failure then names it.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { flattenTrees } from "../scaffold-tests/registry.ts";
+import type { ComponentTree, ProviderRef } from "../types.ts";
+import {
+  type ImportBinding,
+  type ParsedComponentUnit,
+  type ParsedFile,
+  parseFile,
+} from "./parseFile.ts";
+import { reexportTableOf } from "./reexportTable.ts";
+import { ModuleResolver } from "./resolveModule.ts";
+import type { SourceFileCache } from "./sourceCache.ts";
+
+/**
+ * Props whose value is a component the render tree mounts. Chakra and
+ * styled-components use `as`, MUI uses `component` plus the `components` /
+ * `slots` object maps, Radix-adjacent APIs use `fallback`, and the general form
+ * is `render`. `<Button as={Link}>` renders `<Link>`: no JSX tag ever names it,
+ * so the tag walk below is blind to it and the provider requirement vanishes.
+ *
+ * Measured on tonkeeper/ton-console: 7 files write `as={Link}` with Link from
+ * react-router-dom, and every spec of those components died at mount with
+ * `Cannot destructure property 'basename' of useContext(...) as it is null`
+ * from react-router-dom's own `LinkWithRef` — 18 failures, the component never
+ * having written a `<Link>` to blame.
+ */
+const COMPONENT_PASSING_PROPS = new Set([
+  "as",
+  "asComponent",
+  "component",
+  "components",
+  "slots",
+  "fallback",
+  "fallbackAs",
+  "render",
+]);
+
+/** React's own hooks — none of them names a provider. */
+const CORE_HOOKS = new Set([
+  "useCallback",
+  "useContext",
+  "useDebugValue",
+  "useDeferredValue",
+  "useEffect",
+  "useId",
+  "useImperativeHandle",
+  "useInsertionEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useOptimistic",
+  "useReducer",
+  "useRef",
+  "useSyncExternalStore",
+  "useTransition",
+  "useActionState",
+  "useFormState",
+  "useFormStatus",
+  "useActionCount",
+  "useReportError",
+]);
+
+export const providerKey = (info: { filePath: string; componentName: string }): string =>
+  `${info.filePath}::${info.componentName}`;
+
+const provKey = (ref: ProviderRef): string => `${ref.filePath}::${ref.componentName}`;
+
+/** Internal import (relative or tsconfig alias): its bindings are not primitives. */
+const isInternalSpecifier = (s: string): boolean =>
+  s.startsWith(".") || s.startsWith("@/") || s.startsWith("~/");
+
+/** Every bare module specifier that carries a shim's provider-gated surface:
+ *  the canonical `module` plus any alias that re-exports the same thing. */
+const shimModules = (spec: { module: string; modules?: string[] }): string[] => [
+  spec.module,
+  ...(spec.modules ?? []),
+];
+
+/**
+ * Providers the project cannot be expected to import: the context lives in a
+ * node_modules library, and its hooks throw when no library provider sits
+ * above the mount — "No QueryClient set, use QueryClientProvider to set one"
+ * is the dominant class when a suite first meets a react-query app. The route
+ * tree mounts these and NO analysed component ever imports them, so the
+ * derivation synthesises a generated provider module instead.
+ *
+ * Placement is the importing package's root: bare library imports from the
+ * generated file resolve through THAT package's node_modules. An outDir shim
+ * would resolve through the suite's, and workspaces that hoist nothing (bun's
+ * per-package default) could never find the library there.
+ */
+interface LibraryShimSpec {
+  module: string;
+  /**
+   * Other bare module specifiers that carry the SAME provider-gated surface:
+   * `react-router-dom` re-exports the `react-router` core (v5 and v6 do that,
+   * v7 moved it and left the old name as the alias), so the same hook or
+   * component can arrive under either name and needs the same provider. The
+   * generated wrap imports the provider from whichever of these the importing
+   * package can actually resolve — see shimImportModule for why "always the
+   * canonical one" was measured to be wrong.
+   */
+  modules?: string[];
+  hooks: string[];
+  /**
+   * Provider-gated COMPONENTS, the same requirement seen from the other side:
+   * a file that renders `<FormattedMessage>` calls no hook of the library at
+   * all, and the mount throws exactly the same "needs to exist in the
+   * component tree". saleor-dashboard is the evidence — 1038 files import
+   * react-intl and most of them only ever render the component.
+   */
+  components?: string[];
+  componentName: string;
+  fileBase: string;
+  /**
+   * Provider component names this shim makes redundant. The data router serves
+   * every hook and tag the MemoryRouter wrap exists for, so a component that
+   * calls `useNavigate` AND `useLoaderData` gets one provider rather than two
+   * nested ones — the outer would only be shadowed by the inner.
+   */
+  supersedes?: string[];
+  /**
+   * Oldest installed version of the resolved module this shim may be emitted
+   * against, as `[major, minor]`. A wrap that imports a name the installed
+   * library never exported does not skip itself politely: the unresolved import
+   * kills every spec that imports the file. A version that cannot be read is
+   * accepted — refusing a capable library over an unreadable package.json is
+   * the worse bet.
+   */
+  minVersion?: readonly [number, number];
+  /**
+   * Imports for the generated module (the React types included). `{{module}}`
+   * is replaced with the specifier the provider is actually imported from —
+   * which for a module with alias names is not always `module`. See
+   * shimImportModule.
+   */
+  imports: string;
+  /**
+   * Module-level declarations emitted between the imports and the exported
+   * provider, for a shim whose body needs a helper of its own. Blank lines are
+   * added by the template.
+   */
+  helpers?: string;
+  /** Component body: mounts the library's real provider. */
+  body: string;
+}
+
+const LIBRARY_SHIMS: LibraryShimSpec[] = [
+  {
+    module: "@tanstack/react-query",
+    hooks: [
+      "useInfiniteQuery",
+      "useIsFetching",
+      "useIsMutating",
+      "useMutation",
+      "useMutationState",
+      "useQueries",
+      "useQuery",
+      "useQueryClient",
+      "useQueryErrorResetBoundary",
+      "useSuspenseInfiniteQuery",
+      "useSuspenseQuery",
+    ],
+    componentName: "FlawlessQueryClientProvider",
+    fileBase: "flawless-query-client.tsx",
+    imports: `import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { type ReactNode, useState } from "react";`,
+    body: `  // Fresh client per mount — state must not leak between specs — and no
+  // retries: a spec never reaches a real backend, and a retry storm buries
+  // the one error worth seeing.
+  const [client] = useState(
+    () => new QueryClient({ defaultOptions: { queries: { retry: false } } }),
+  );
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;`,
+  },
+  {
+    // nakama is a client-rendered router-dom SPA: CommandPalette calls
+    // useNavigate and the mount dies with "useNavigate() may be used only in
+    // the context of a <Router>". MemoryRouter is the standard test context.
+    module: "react-router-dom",
+    // The same surface is also exported by `react-router` itself: v5 and v6
+    // re-export the core through react-router-dom, v7 moved it and left the old
+    // name as the alias. saleor-dashboard writes both (146 files against
+    // react-router-dom, 48 against react-router), and a component that renders
+    // <Link> calls no hook at all — "You should not use <Link> outside a
+    // <Router>" is what the mount says for it.
+    modules: ["react-router"],
+    // `Outlet` and `Navigate` join `Link` here on measurement, not on the
+    // library's surface list: tonkeeper/ton-console's Layout and LayoutSolid
+    // render <Outlet /> and died with `Cannot destructure property 'basename'
+    // of useContext(...) as it is null` — the same missing RouterContext, from
+    // a tag the walk could always see. Under MemoryRouter an <Outlet /> with
+    // no routes renders nothing, which is the honest shape of a unit test: the
+    // layout is what the spec mounts, the routed child is not in it.
+    components: ["Link", "NavLink", "Navigate", "Outlet"],
+    hooks: [
+      "useHref",
+      "useLinkClickHandler",
+      "useLocation",
+      "useNavigate",
+      "useOutlet",
+      "useOutletContext",
+      "useParams",
+      "useRoutes",
+      "useSearchParams",
+    ],
+    componentName: "FlawlessRouterProvider",
+    fileBase: "flawless-router.tsx",
+    imports: `import type { ReactNode } from "react";
+import { MemoryRouter } from "{{module}}";`,
+    body: `  // An in-memory router rooted at "/": navigation hooks work, nothing moves
+  // a real history, and no spec leaks location state into the next.
+  // The data-router hooks (useLoaderData, useFetcher, useSubmit …) are NOT
+  // served from here — MemoryRouter leaves DataRouterContext empty and they
+  // throw for it. They get FlawlessDataRouterProvider below instead.
+  return <MemoryRouter>{children}</MemoryRouter>;`,
+  },
+  {
+    // The same router from the other side of 6.4. These hooks read the DATA
+    // router and `invariant` out under MemoryRouter — "`useLoaderData` must be
+    // used within a data router" — 110 failures across 26 spec files of
+    // code-forge-io/react-router-devtools and 28 across 11 of
+    // remix-run/remix-store: both apps' components ARE route modules, and no
+    // wrap short of a data router can mount them. The names are read off
+    // react-router 7.9.3's own useDataRouterContext/useDataRouterState call
+    // sites, minus `useNavigate`, which MemoryRouter does serve (nakama is the
+    // proof) — plus `useRouterState`, whose invariant fires as its unstable
+    // alias.
+    //
+    // The component side of the same split, probed rather than assumed — each
+    // tag rendered alone under both wraps in remix-store's own suite:
+    //   PROBE Form:              memory=useSubmit must be used within a data router
+    //   PROBE ScrollRestoration: memory=useMatches must be used within a data router
+    //   PROBE Link / Outlet:     memory=<no throw> (they stay above)
+    // `<Form>` is what killed unit/Welcome.test.tsx and the custom-server
+    // Home of code-forge-io/react-router-devtools: the tag is a router
+    // component, the file never names a data hook, so the hook walk found
+    // nothing to key on. `<Await>` was also probed and is NOT gated — given
+    // the `resolve` a generated spec actually passes (none) it mounts under
+    // MemoryRouter; the remix-store `useFetcher` deaths that looked like it
+    // were a wrapper-reached data hook, fixed separately.
+    components: ["Form", "ScrollRestoration"],
+    module: "react-router-dom",
+    modules: ["react-router"],
+    // The library's data APIs (`createMemoryRouter`, `RouterProvider`) ship
+    // from 6.4; on 5.x or 6.0-6.3 this wrap is not offered and those hooks keep
+    // failing with the honest message the library itself writes.
+    minVersion: [6, 4],
+    hooks: [
+      "unstable_useRouterState",
+      "useActionData",
+      "useBlocker",
+      "useFetcher",
+      "useFetchers",
+      "useLoaderData",
+      "useMatches",
+      "useNavigation",
+      "useRevalidator",
+      "useRouteError",
+      "useRouteLoaderData",
+      "useRouterState",
+      "useScrollRestoration",
+      "useSubmit",
+      "useViewTransitionState",
+    ],
+    supersedes: ["FlawlessRouterProvider"],
+    componentName: "FlawlessDataRouterProvider",
+    fileBase: "flawless-data-router.tsx",
+    imports: `import type { ReactNode } from "react";
+import { createMemoryRouter, RouterProvider, useRouteError } from "{{module}}";`,
+    helpers: `/** Rethrows instead of rendering: see the provider below for why. */
+function FlawlessRouteError(): never {
+  throw useRouteError();
+}`,
+    body: `  // An in-memory DATA router rooted at "/". The hooks above read loader and
+  // action data off it and get NOTHING — undefined, not invented data — which
+  // is the honest unit shape: the route module mounts, its data does not exist.
+  //
+  // RouterProvider wraps the tree in its own error boundary, and its default
+  // error UI is <h2>Unexpected Application Error!</h2><h3>…</h3>. Measured: that
+  // markup is what a throwing component leaves behind even with
+  // \`errorElement: null\`, so a spec asserting a heading would pass against the
+  // router's error page. Rethrowing the route error makes React walk past the
+  // boundary and out of render(), so a crash fails its own spec with its own
+  // error, exactly as it does under MemoryRouter.
+  //
+  // Built per render rather than memoised so \`children\` stays current for a
+  // caller that re-renders the wrap; unit specs mount once, and a fresh router
+  // per mount is what MemoryRouter does internally too.
+  const router = createMemoryRouter(
+    [{ path: "*", element: <>{children}</>, errorElement: <FlawlessRouteError /> }],
+    { initialEntries: ["/"] },
+  );
+  return <RouterProvider router={router} />;`,
+  },
+  {
+    // Form-through-context: useFormContext / useController / useWatch /
+    // useFieldArray / useFormState read the form off React context and get
+    // NULL with no FormProvider above the mount, which the library then
+    // dereferences — "Cannot read properties of null (reading 'control')".
+    // Wrapping is what the library's own test docs prescribe. Discovered on
+    // invoify's shadcn form.tsx, where it is also NOT the whole story: that
+    // FormField spec passes no props at all, because its contract arrives as
+    // one opaque spread (...props: ControllerProps<…> from node_modules), so
+    // with the wrap in place it fails one level deeper on the missing `name`.
+    // A required prop the analyser cannot see is a different gap, and stays a
+    // documented tail rather than being papered over with a invented form.
+    // A component that supplies `control` itself is wrapped for nothing: an
+    // outer provider loses to an explicit control, so the wrap stays harmless.
+    //
+    // React 19 exports its own useFormState, and the gate matches on the
+    // IMPORTED MODULE as well as the name (deriveContextProviderWraps), so
+    // listing it here cannot wrap a component that got it from "react".
+    module: "react-hook-form",
+    hooks: [
+      "useController",
+      "useFieldArray",
+      "useFormState",
+      "useWatch",
+      // The read-only accessor the rest of the family is built on, and the one
+      // shadcn's form.tsx imports directly.
+      "useFormContext",
+    ],
+    componentName: "FlawlessFormProvider",
+    fileBase: "flawless-form.tsx",
+    imports: `import type { ReactNode } from "react";
+import { FormProvider, useForm } from "react-hook-form";`,
+    body: `  // A form with no defaultValues and nothing wired to submit: a field
+  // component's contract is about the field, not about data, and an unset value
+  // is the honest starting point for a spec that supplies none. Fresh per mount
+  // so one spec's typing cannot leak into the next spec's formState.
+  const methods = useForm();
+  return <FormProvider {...methods}>{children}</FormProvider>;`,
+  },
+  {
+    // The dominant failure class when a suite first meets a react-intl app:
+    // "[React Intl] Could not find required `intl` object. <IntlProvider>
+    // needs to exist in the component tree" — 715 of saleor-dashboard's 1171
+    // failing spec files, and the same shape anywhere the app formats copy
+    // through the library. An IntlProvider with a locale and no message table
+    // resolves every message back to its own `defaultMessage`, which is the
+    // literal text the source wrote and the specs assert on: so the wrap makes
+    // the mount work WITHOUT inventing a translation, and an assertion that
+    // still fails is failing on the component, not on a missing context.
+    // `useIntl().formatMessage` reads the same empty table for the same reason.
+    module: "react-intl",
+    hooks: ["useIntl", "useCreateIntl", "useFormatters"],
+    components: [
+      "FormattedMessage",
+      "FormattedDate",
+      "FormattedNumber",
+      "FormattedTime",
+      "FormattedPlural",
+      "FormattedList",
+      "FormattedListParts",
+      "FormattedRelativeTime",
+      "FormattedHTMLMessage",
+    ],
+    componentName: "FlawlessIntlProvider",
+    fileBase: "flawless-intl.tsx",
+    imports: `import type { ReactNode } from "react";
+import { IntlProvider } from "react-intl";`,
+    body: `  // "en" is not a claim about the app's locales, it is the locale of the
+  // strings the source itself wrote. Nothing is fetched, so nothing can hang a
+  // spec; onError is left alone because a genuinely missing message is a real
+  // finding and should still print.
+  return <IntlProvider locale="en">{children}</IntlProvider>;`,
+  },
+];
+
+/**
+ * Provider name → the provider that makes it redundant, read off the shim
+ * table. Applied where a component's requirements are finalised, so the rule
+ * survives the transitive walk that produced the pair.
+ */
+const SUPERSEDED_BY: Map<string, string> = new Map(
+  LIBRARY_SHIMS.flatMap((s) => (s.supersedes ?? []).map((n) => [n, s.componentName] as const)),
+);
+
+export interface LibraryProviderShim {
+  /** Bare module specifier whose hooks need the wrap. */
+  module: string;
+  /** Alias module specifiers for the same surface (see LibraryShimSpec). */
+  modules?: string[];
+  /** Module-side hook names that require the provider above them. */
+  hooks: string[];
+  /** Module-side component names that require it too (see LibraryShimSpec). */
+  components?: string[];
+  /** The generated component to wrap with. */
+  componentName: string;
+  /** Absolute path of the module that exports componentName. */
+  filePath: string;
+}
+
+/** Nearest directory whose package.json claims this file. */
+function packageRootOf(file: string): string {
+  const fallback = path.dirname(path.resolve(file));
+  let dir = fallback;
+  for (;;) {
+    try {
+      if (statSync(path.join(dir, "package.json")).isFile()) return dir;
+    } catch {
+      // Keep walking: a directory with no package.json is simply not one.
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return fallback;
+    dir = parent;
+  }
+}
+
+/**
+ * Every bare module specifier the harness answers with a provider shim — the
+ * canonical name plus its alias modules (`react-router` beside
+ * `react-router-dom`). Exported for the bootability report: a shimmed module
+ * needs no package on disk, so calling it "not installed" would be a false
+ * alarm about a suite that mounts fine.
+ */
+export function providerShimModules(): string[] {
+  return LIBRARY_SHIMS.flatMap((spec) => [spec.module, ...(spec.modules ?? [])]);
+}
+
+/** One shim per (library, importing package) pair the analysis can reach. */
+export function libraryProviderShimsFor(componentFiles: string[]): LibraryProviderShim[] {
+  const roots = new Set<string>();
+  for (const file of componentFiles) roots.add(packageRootOf(file));
+  const out: LibraryProviderShim[] = [];
+  for (const spec of LIBRARY_SHIMS) {
+    for (const root of roots) {
+      const filePath = path.join(root, ".flawless", spec.fileBase);
+      // A library too old for this shim's surface is not a wrap to skip: the
+      // file would import a name the installed package never exported, and one
+      // unresolved import takes down every spec that reads the shim. Refusing
+      // to OFFER the shim keeps such a component on whichever wrap the library
+      // can serve — and on the library's own honest error for the rest.
+      if (!shimAvailableAt(spec, filePath)) continue;
+      out.push({
+        module: spec.module,
+        modules: spec.modules,
+        hooks: spec.hooks,
+        components: spec.components,
+        componentName: spec.componentName,
+        filePath,
+      });
+    }
+  }
+  return out;
+}
+
+/** The shims a wrap map actually references — a scaffold writes those files
+ *  only when something in the run will import them. */
+export function referencedLibraryShims(
+  wraps: Map<string, ProviderRef[]> | undefined,
+  componentFiles: string[],
+): LibraryProviderShim[] {
+  if (!wraps || wraps.size === 0) return [];
+  const used = new Set<string>();
+  for (const refs of wraps.values()) {
+    for (const r of refs) used.add(`${r.filePath}::${r.componentName}`);
+  }
+  return libraryProviderShimsFor(componentFiles).filter((s) =>
+    used.has(`${s.filePath}::${s.componentName}`),
+  );
+}
+
+/**
+ * Which specifier the generated shim imports its provider from, and what
+ * version of it the importing package will actually get.
+ *
+ * The canonical name is what most apps import, not what every app HAS. The
+ * router shim says `react-router-dom`, and an app on react-router v7 has only
+ * `react-router` — measured on remix-run/remix-store: `react-router@7.18.2`
+ * installed, `react-router-dom` absent from both node_modules and package.json.
+ * There the generated file's own import is unresolvable, and that is not a
+ * skipped wrap: `Failed to resolve import "react-router-dom" from
+ * "flawless-router.tsx"` kills every spec that imports the shim, so components
+ * that never touched the router die too. Asking the importing package what it
+ * has is the difference between a suite that mounts and one that cannot load.
+ *
+ * Canonical first, so an app carrying both names keeps the behaviour it was
+ * measured with (saleor-dashboard: react-router-dom and react-router, both
+ * 5.3.4), and falling back to canonical when nothing resolves keeps the loud
+ * failure the shim was designed to be.
+ *
+ * Resolution walks up from the shim file's own directory because that is the
+ * walk the import performs at runtime: `<pkg>/.flawless/`, then
+ * `<pkg>/node_modules`, then out through a workspace.
+ *
+ * `min` is the same question asked one level finer. Two apps of the same family
+ * can carry different capabilities (react-router-dom 5.x has no
+ * `createMemoryRouter`; 6.4 introduced it), and an alias that is too old is
+ * skipped for the next candidate rather than emitted as a broken import.
+ */
+function shimImportModule(
+  spec: LibraryShimSpec,
+  fromShimFile: string,
+  min: readonly [number, number] | undefined = spec.minVersion,
+): { module: string; version?: string } {
+  const fromDir = path.dirname(fromShimFile);
+  let firstResolved: { module: string; version?: string } | undefined;
+  for (const candidate of shimModules(spec)) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+      const packageJson = path.join(dir, "node_modules", candidate, "package.json");
+      if (existsSync(packageJson)) {
+        const found = { module: candidate, version: installedVersion(packageJson) };
+        firstResolved ??= found;
+        if (min === undefined || meetsMinimum(found.version, min)) return found;
+        break;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return firstResolved ?? { module: spec.module };
+}
+
+/** The version a package.json names, or undefined when it cannot be read. */
+function installedVersion(packageJson: string): string | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(packageJson, "utf8")) as { version?: unknown };
+    return typeof raw.version === "string" ? raw.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `[major, minor]` of an installed version; a range or a non-version is none. */
+function meetsMinimum(version: string | undefined, min: readonly [number, number]): boolean {
+  // Unreadable is accepted, not refused: see LibraryShimSpec.minVersion.
+  if (version === undefined) return true;
+  const got = /^\D*(\d+)(?:\.(\d+))?/.exec(version);
+  if (!got) return true;
+  const [major, minor] = [Number(got[1]), Number(got[2] ?? 0)];
+  return major > min[0] || (major === min[0] && minor >= min[1]);
+}
+
+/** Whether this shim may be emitted for a package root at all: false only on
+ *  positive evidence that the library the shim imports is too old for it. */
+function shimAvailableAt(spec: LibraryShimSpec, shimFilePath: string): boolean {
+  if (spec.minVersion === undefined) return true;
+  return meetsMinimum(shimImportModule(spec, shimFilePath).version, spec.minVersion);
+}
+
+/** Source for the generated module: the real library provider, mounted fresh
+ *  per mount so state never leaks between specs. `shimFilePath` is where the
+ *  generated file will sit, which is what decides the library's import name. */
+export function libraryShimSource(
+  module: string,
+  componentName: string,
+  shimFilePath?: string,
+): string {
+  const spec = LIBRARY_SHIMS.find((s) => s.module === module && s.componentName === componentName);
+  if (!spec) return "";
+  const from = shimFilePath ? shimImportModule(spec, shimFilePath).module : spec.module;
+  const prelude = [spec.imports.replaceAll("{{module}}", from), spec.helpers]
+    .filter(Boolean)
+    .join("\n\n");
+  return `// Generated by flawless-react. Do not edit: regenerations overwrite it.
+// The provider lives here, inside the importing package, because a bare
+// import of ${from} only resolves through this package's node_modules.
+${prelude}
+
+export function ${componentName}({ children }: { children?: ReactNode }) {
+${spec.body}
+}
+`;
+}
+
+interface NamespaceFacts {
+  /** Components that render N.<member> without already rendering N.<something>.Provider. */
+  consumers: Set<string>;
+  /** The file's own provider for that namespace, if it has one. */
+  provider?: ProviderRef;
+}
+
+/**
+ * Third-party compound families inside one file: every component that renders
+ * `Namespace.Member` JSX needs the file's provider component — the one that
+ * renders `Namespace.Provider` (base-ui shape: ToastProvider), else the one
+ * that renders the bare `Namespace` (cmdk shape: Command wrapping
+ * <CommandPrimitive>). Members are identified anywhere in the body because a
+ * part's root is often a styled wrapper, not the primitive itself.
+ */
+/** A JSX tag as (base identifier, last member): Identifier → base only;
+ *  `<A.B.C>` parses as a PropertyAccessExpression chain (TS 5.x) — QualifiedName
+ *  handling stays for old ASTs. */
+function tagNameParts(tag: ts.JsxTagNameExpression | ts.QualifiedName): {
+  base: string;
+  member?: string;
+} {
+  if (ts.isIdentifier(tag)) return { base: tag.text };
+  if (ts.isQualifiedName(tag)) {
+    return ts.isIdentifier(tag.left)
+      ? { base: tag.left.text, member: tag.right.text }
+      : { base: "" };
+  }
+  if (ts.isPropertyAccessExpression(tag)) {
+    const parts: string[] = [];
+    let node: ts.Node = tag;
+    while (ts.isPropertyAccessExpression(node)) {
+      parts.unshift(node.name.text);
+      node = node.expression;
+    }
+    return ts.isIdentifier(node)
+      ? { base: node.text, member: parts[parts.length - 1] }
+      : { base: "" };
+  }
+  return { base: "" };
+}
+
+/**
+ * Whether the provider can be mounted with NO props and still supply what
+ * consumers read from the context. A typed-literal prop beyond `children`
+ * that is neither optional nor rescued by a destructuring default cannot
+ * mount bare: <ChartProvider value={...}> mounts with value undefined and
+ * every consumer's context check throws right back out — the wrap only
+ * relocates the error, so the wrap must not be added. Anything the shape
+ * analysis cannot judge (a `props` identifier, a type reference instead of
+ * a literal) is assumed mountable: the rule stays opportunistic.
+ */
+function providerMountsBare(unit: ParsedComponentUnit): boolean {
+  const lit = unit.propsTypeLiteral;
+  if (!lit) return true;
+  // bodyNode is the function for `export function P(...)` and the body for
+  // other shapes — the parameter lives on either node, and parent links are
+  // not guaranteed, so check the node itself and its parent directly.
+  const fnNode = [unit.bodyNode, unit.bodyNode.parent].find(
+    (n): n is ts.FunctionLikeDeclaration =>
+      n !== undefined && ts.isFunctionLike(n) && n.parameters.length > 0,
+  );
+  const firstParam = fnNode?.parameters[0];
+  const pattern =
+    firstParam && ts.isObjectBindingPattern(firstParam.name) ? firstParam.name : undefined;
+  const defaulted = new Set<string>();
+  if (pattern) {
+    for (const el of pattern.elements) {
+      if (el.initializer && ts.isIdentifier(el.name)) defaulted.add(el.name.text);
+    }
+  }
+  return lit.members.every((m) => {
+    if (!ts.isPropertySignature(m) || !m.name || !ts.isIdentifier(m.name)) return true;
+    const name = m.name.text;
+    if (name === "children" || m.questionToken) return true;
+    return defaulted.has(name);
+  });
+}
+
+/**
+ * Providers whose NAME breaks the `useX` → `XProvider` convention: the hook
+ * reads a context object, and the provider component renders that object's
+ * `.Provider` — chanhdai's `useCollapsible` is fed by `CollapsibleWithContext`
+ * (exported, no less, as `Collapsible`). The context object is the ground
+ * truth both the hook and the provider must mention, so read it: a hook
+ * supplies a context when it calls `useContext(Ctx)` itself or reaches one
+ * through hooks defined in the same file.
+ */
+/** A context object as one file mentions it: imported (module, exported name)
+ *  or locally defined (no module). Resolved to (file::name) keys by the caller,
+ *  which owns the async ModuleResolver. */
+interface RawCtxRef {
+  module?: string;
+  name: string;
+}
+
+const rawCtxRefFor = (ident: string, imports: Map<string, ImportBinding>): RawCtxRef => {
+  const b = imports.get(ident);
+  if (!b || b.isTypeOnly) return { name: ident };
+  return { module: b.specifier, name: b.importedName ?? ident };
+};
+
+interface CtxFacts {
+  /** Module-side hook name → provider component name in the same file. */
+  providerByHook: Map<string, string>;
+  /** Module-side hook name → every context object it reads (transitively). */
+  readsRaw: Map<string, Set<RawCtxRef>>;
+  /** Component name → the first context object it renders as `<Ctx.Provider>`. */
+  suppliesRaw: Map<string, RawCtxRef>;
+  /** Module-side hook name → shim-library modules whose provider-gated hooks
+   *  it calls, possibly through local wrappers (the useSaveTelegramSettings
+   *  shape: a project hook wrapping useMutation). */
+  libsByHook: Map<string, Set<string>>;
+  /** Hook name → every callee identifier in its body (direct, not closed
+   *  over). Derive follows the ones that are cross-file import bindings so
+   *  two-level wrappers — useMcpServerDialogState → useMcpServerDetailQuery
+   *  → useQuery — still reach the library. */
+  callsByHook: Map<string, Set<string>>;
+  /** Component name → bare JSX tag names that component's body renders. The
+   *  library shim table reads it for the components a file IMPORTS: rendering
+   *  a provider-gated component requires the provider exactly like calling its
+   *  hook does, and calls are all the scan above can see. */
+  tagsByFn: Map<string, Set<string>>;
+  /** Hook names this file declares, as opposed to handing along. */
+  declaredHooks: Set<string>;
+  /** `export { useX, useY as useZ } from './m'`: the exported name → the module
+   *  it came from and the name that module uses. Re-export barrels are how a
+   *  Feature-Sliced app hands a hook to the component that imports its index. */
+  reexportedHooks: Map<string, { specifier: string; imported: string }[]>;
+  /** The bare `export * from './m'` specifiers, which carry every name. */
+  starSpecifiers: string[];
+}
+
+function ctxFactsOf(parsed: ParsedFile): CtxFacts {
+  // Local hook definitions: name → body node.
+  const bodies = new Map<string, ts.Node>();
+  const collect = (n: ts.Node): void => {
+    if (ts.isFunctionDeclaration(n) && n.name && n.body) {
+      if (/^use[A-Z]/.test(n.name.text) && !CORE_HOOKS.has(n.name.text)) {
+        bodies.set(n.name.text, n.body);
+      }
+    } else if (ts.isVariableStatement(n)) {
+      for (const d of n.declarationList.declarations) {
+        if (
+          ts.isIdentifier(d.name) &&
+          /^use[A-Z]/.test(d.name.text) &&
+          !CORE_HOOKS.has(d.name.text) &&
+          d.initializer &&
+          ts.isFunctionLike(d.initializer) &&
+          d.initializer.body
+        ) {
+          bodies.set(d.name.text, d.initializer.body);
+        }
+      }
+    }
+    ts.forEachChild(n, collect);
+  };
+  for (const stmt of parsed.sourceFile.statements) collect(stmt);
+
+  // The file's own hooks, as opposed to the ones it hands along: the barrel
+  // walk hops only when a name is not declared here.
+  const declaredHooks = new Set(bodies.keys());
+  const { named: reexportedHooks, stars: starSpecifiers } = reexportTableOf(parsed.sourceFile);
+
+  const direct = new Map<string, { ctx: Set<string>; calls: Set<string>; libs: Set<string> }>();
+  for (const [hook, body] of bodies) {
+    const ctx = new Set<string>();
+    const calls = new Set<string>();
+    const libs = new Set<string>();
+    const scan = (n: ts.Node): void => {
+      if (ts.isCallExpression(n)) {
+        // `useContext(Ctx)` and `React.useContext(Ctx)` — the namespace form
+        // is how `import * as React` files write it.
+        const fn = ts.isIdentifier(n.expression)
+          ? n.expression.text
+          : ts.isPropertyAccessExpression(n.expression)
+            ? n.expression.name.text
+            : undefined;
+        const firstArg = n.arguments[0];
+        if (fn === undefined) {
+          // nothing to key on
+        } else if (fn === "useContext" && firstArg && ts.isIdentifier(firstArg)) {
+          ctx.add(firstArg.text);
+        } else {
+          calls.add(fn);
+          // A callee that is an IMPORT of a provider-gated library hook means
+          // this local hook needs the library's provider too — the
+          // useSaveTelegramSettings shape: a project hook wrapping useMutation.
+          const b = parsed.imports.get(fn);
+          if (b && !b.isTypeOnly) {
+            for (const s of LIBRARY_SHIMS) {
+              if (shimModules(s).includes(b.specifier) && s.hooks.includes(b.importedName ?? fn)) {
+                libs.add(s.module);
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(n, scan);
+    };
+    scan(body);
+    direct.set(hook, { ctx, calls, libs });
+  }
+
+  // Transitively close over local hook calls: useCollapsibleAnimation reads
+  // the context through the useCollapsible it calls.
+  const read = new Map<string, Set<string>>();
+  for (const [hook, { ctx }] of direct) read.set(hook, new Set(ctx));
+  const readLibs = new Map<string, Set<string>>();
+  for (const [hook, { libs }] of direct) readLibs.set(hook, new Set(libs));
+  const readCalls = new Map<string, Set<string>>();
+  for (const [hook, { calls }] of direct) readCalls.set(hook, new Set(calls));
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [hook, { calls }] of direct) {
+      const mine = read.get(hook);
+      const mineLibs = readLibs.get(hook);
+      const mineCalls = readCalls.get(hook);
+      if (!mine || !mineLibs || !mineCalls) continue;
+      for (const called of calls) {
+        if (called === hook) continue;
+        const sub = read.get(called);
+        if (sub)
+          for (const ident of sub) {
+            if (!mine.has(ident)) {
+              mine.add(ident);
+              grew = true;
+            }
+          }
+        const subLibs = readLibs.get(called);
+        if (subLibs)
+          for (const m of subLibs) {
+            if (!mineLibs.has(m)) {
+              mineLibs.add(m);
+              grew = true;
+            }
+          }
+        // Callers reach libraries through local hooks too: merge the whole
+        // callee set so the cross-file walk below sees calls the chain makes.
+        const subCalls = readCalls.get(called);
+        if (subCalls)
+          for (const c2 of subCalls) {
+            if (!mineCalls.has(c2)) {
+              mineCalls.add(c2);
+              grew = true;
+            }
+          }
+      }
+    }
+  }
+
+  // Components rendering <Ctx.Provider> — the supplier per context object,
+  // both by identifier text (same-file pairing) and by raw (module, name)
+  // reference for the cross-file join.
+  const supplier = new Map<string, string>();
+  const suppliesRaw = new Map<string, RawCtxRef>();
+  for (const u of parsed.components) {
+    const visit = (n: ts.Node): void => {
+      if (
+        (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) &&
+        ts.isPropertyAccessExpression(n.tagName) &&
+        n.tagName.name.text === "Provider" &&
+        ts.isIdentifier(n.tagName.expression)
+      ) {
+        const ident = n.tagName.expression.text;
+        supplier.set(ident, u.componentName);
+        if (!suppliesRaw.has(u.componentName)) {
+          suppliesRaw.set(u.componentName, rawCtxRefFor(ident, parsed.imports));
+        }
+      }
+      ts.forEachChild(n, visit);
+    };
+    visit(u.bodyNode);
+  }
+
+  const providerByHook = new Map<string, string>();
+  for (const [hook, ctxs] of read) {
+    for (const ident of ctxs) {
+      const p = supplier.get(ident);
+      if (p && p !== hook) {
+        providerByHook.set(hook, p);
+        break;
+      }
+    }
+  }
+  const readsRaw = new Map<string, Set<RawCtxRef>>();
+  for (const [hook, ctxs] of read) {
+    const refs = new Set<RawCtxRef>();
+    for (const ident of ctxs) {
+      const r = rawCtxRefFor(ident, parsed.imports);
+      if (![...refs].some((e) => e.module === r.module && e.name === r.name)) refs.add(r);
+    }
+    readsRaw.set(hook, refs);
+  }
+  const libsByHook = new Map<string, Set<string>>();
+  for (const [hook, libs] of readLibs) if (libs.size > 0) libsByHook.set(hook, libs);
+  // The JSX tags each of this file's components renders, keyed by component
+  // name — the same requirement, seen where the hook scan above is blind: a
+  // component that renders <FormattedMessage> calls no hook of the library at
+  // all. A bare tag is recorded because that is what an import binding names,
+  // and so is a component handed through a prop (`as={Link}`, `slots={{ root:
+  // Link }}`) — same mount, same provider, no tag. `Namespace.Member` stays
+  // namespaceFacts' business.
+  const tagsByFn = new Map<string, Set<string>>();
+  for (const u of parsed.components) {
+    if (!u.bodyNode) continue;
+    const tags = new Set<string>();
+    const passedByProp = (expr: ts.Expression): void => {
+      if (ts.isIdentifier(expr)) {
+        tags.add(expr.text);
+        return;
+      }
+      if (ts.isObjectLiteralExpression(expr)) {
+        for (const prop of expr.properties) {
+          if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.initializer)) {
+            tags.add(prop.initializer.text);
+          }
+        }
+      }
+    };
+    const visitTags = (n: ts.Node): void => {
+      if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+        const { base, member } = tagNameParts(n.tagName);
+        if (base && !member) tags.add(base);
+      } else if (ts.isJsxAttribute(n) && ts.isIdentifier(n.name)) {
+        if (COMPONENT_PASSING_PROPS.has(n.name.text) && n.initializer) {
+          const expr = ts.isJsxExpression(n.initializer) ? n.initializer.expression : n.initializer;
+          if (expr) passedByProp(expr);
+        }
+      }
+      ts.forEachChild(n, visitTags);
+    };
+    visitTags(u.bodyNode);
+    tagsByFn.set(u.componentName, tags);
+  }
+  return {
+    providerByHook,
+    readsRaw,
+    suppliesRaw,
+    libsByHook,
+    callsByHook: readCalls,
+    tagsByFn,
+    declaredHooks,
+    reexportedHooks,
+    starSpecifiers,
+  };
+}
+
+export function namespaceFacts(parsed: ParsedFile): NamespaceFacts {
+  const external = new Set<string>();
+  for (const [local, b] of parsed.imports) {
+    if (b.isTypeOnly || isInternalSpecifier(b.specifier)) continue;
+    external.add(local);
+  }
+  const consumers = new Set<string>();
+  if (external.size === 0) return { consumers };
+  // Per unit, which external namespaces it touches as `<N>` (bare) or as
+  // `<N.Member>`. A namespace only becomes a COMPOUND family when the file
+  // shows both sides: members somewhere, and a provider — a `<N.Provider>`
+  // renderer (base-ui) or a bare `<N>` renderer (cmdk). Icon imports render
+  // bare with no members — they are leaves, not providers, and the pairing
+  // requirement is what keeps them out.
+  const usage: {
+    bare: Set<string>;
+    bareAll: Set<string>;
+    provider: Set<string>;
+    root: Set<string>;
+    member: Set<string>;
+  }[] = [];
+  for (const u of parsed.components) {
+    const rec = {
+      bare: new Set<string>(),
+      bareAll: new Set<string>(),
+      provider: new Set<string>(),
+      root: new Set<string>(),
+      member: new Set<string>(),
+    };
+    const visit = (n: ts.Node): void => {
+      if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+        const { base, member } = tagNameParts((n as ts.JsxOpeningLikeElement).tagName);
+        if (!member && ts.isIdentifier((n as ts.JsxOpeningLikeElement).tagName)) {
+          rec.bareAll.add(base);
+        }
+        if (external.has(base)) {
+          if (!member) rec.bare.add(base);
+          // `.Root` cuts both ways: base-ui's N.Root REQUIRES the context its
+          // N.Provider supplies (Toast.Root), while radix's namespace shape
+          // makes N.Root the provider itself (Dialog.Root). It is recorded as
+          // both a candidate and a member; providerFor demotes it wherever an
+          // explicit N.Provider renderer exists in the same file.
+          else if (member === "Provider") rec.provider.add(base);
+          else if (member === "Root") {
+            rec.root.add(base);
+            rec.member.add(base);
+          } else rec.member.add(base);
+        }
+      }
+      ts.forEachChild(n, visit);
+    };
+    visit(u.bodyNode);
+    usage.push(rec);
+  }
+  const memberBases = new Set(usage.flatMap((r) => [...r.member]));
+  // A base-ui file names its provider out loud (`<N.Provider>`); a radix
+  // namespace file never does — there the `<N.Root>` renderer IS the
+  // provider. Where an explicit provider exists, `.Root` demotes back to
+  // a plain member (base-ui's Toast.Root needs the ToastProvider wrap).
+  const explicitProvider = (base: string): boolean => usage.some((r) => r.provider.has(base));
+  const rootIsProvider = (r: { root: Set<string> }, base: string): boolean =>
+    r.root.has(base) && !explicitProvider(base);
+  // `const ToastProvider = ToastPrimitives.Provider` — the shadcn shape, where
+  // the provider is an ALIAS of the namespace's own `.Provider` rather than a
+  // component declaration. No parsed unit renders it, so a file full of members
+  // (`Toast` = `ToastPrimitives.Root`) looked unwrappable while exporting
+  // exactly the provider that would have wrapped them: invoify's Toast, Toaster
+  // and every variant spec died on "must be used within ToastProvider". Only an
+  // EXPORTED alias is a wrap — an import is the only way the mount reaches it —
+  // and it outranks the Root-as-provider reading, because a radix Root consumes
+  // that same context: wrapping its members in the Root just reproduces the
+  // throw one level up.
+  const aliasByBase = new Map<string, string[]>();
+  const exportedAs = new Map<string, string>();
+  const markExported = (local: string, exported: string): void => {
+    if (!exportedAs.has(local)) exportedAs.set(local, exported);
+  };
+  const isExportStatement = (n: ts.Node): boolean =>
+    ts.canHaveModifiers(n) &&
+    (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+  for (const stmt of parsed.sourceFile.statements) {
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name)) continue;
+        if (isExportStatement(stmt)) markExported(d.name.text, d.name.text);
+        const init = d.initializer;
+        if (
+          init &&
+          ts.isPropertyAccessExpression(init) &&
+          ts.isIdentifier(init.expression) &&
+          init.name.text === "Provider" &&
+          external.has(init.expression.text)
+        ) {
+          aliasByBase.set(init.expression.text, [
+            ...(aliasByBase.get(init.expression.text) ?? []),
+            d.name.text,
+          ]);
+        }
+      }
+    } else if (ts.isExportDeclaration(stmt)) {
+      const clause = stmt.exportClause;
+      if (clause && ts.isNamedExports(clause)) {
+        for (const spec of clause.elements) {
+          markExported((spec.propertyName ?? spec.name).text, spec.name.text);
+        }
+      }
+    } else if (
+      (ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) &&
+      stmt.name &&
+      isExportStatement(stmt)
+    ) {
+      markExported(stmt.name.text, stmt.name.text);
+    }
+  }
+  const aliasProviderFor = (base: string): ProviderRef | undefined => {
+    for (const local of aliasByBase.get(base) ?? []) {
+      const exported = exportedAs.get(local);
+      if (exported !== undefined)
+        return { componentName: exported, filePath: parsed.filePath, exportKind: "named" };
+    }
+    return undefined;
+  };
+  const providerFor = (base: string): number =>
+    usage.findIndex((r, i) => {
+      const unit = parsed.components[i];
+      return (
+        unit !== undefined &&
+        (r.provider.has(base) || r.bare.has(base) || rootIsProvider(r, base)) &&
+        unit.exportKind !== "none" &&
+        !unit.isAsync &&
+        providerMountsBare(unit)
+      );
+    });
+  let provider: ProviderRef | undefined;
+  for (const base of memberBases) {
+    // An explicit <N.Provider> renderer is the file's own mount surface and
+    // wins; with none, an exported alias of <N.Provider> beats the Root
+    // reading; with neither, the Root (or bare) renderer provides.
+    const aliased = explicitProvider(base) ? undefined : aliasProviderFor(base);
+    const pi = aliased ? -1 : providerFor(base);
+    const unit = pi === -1 ? undefined : parsed.components[pi];
+    // `providerFor` already excludes a unit the file does not export; restating
+    // it here is what narrows `exportKind` to the two kinds a mount can import.
+    const fromUnit: ProviderRef | undefined =
+      unit && unit.exportKind !== "none"
+        ? {
+            componentName: unit.componentName,
+            filePath: parsed.filePath,
+            exportKind: unit.exportKind,
+            exportedAs: unit.exportedAs,
+          }
+        : undefined;
+    const ref = aliased ?? fromUnit;
+    if (!ref) continue;
+    // A unit that mounts the provider itself — as the <N.Provider> tag OR as
+    // the file's wrapper around it (Toaster renders <ToastProvider>, not
+    // <ToastPrimitive.Provider>) — supplies its own context and a nested
+    // second provider can actively break it.
+    const providerTag = ref.componentName;
+    usage.forEach((r, ui) => {
+      const consumer = parsed.components[ui];
+      if (
+        consumer &&
+        r.member.has(base) &&
+        (aliased || (!r.provider.has(base) && !rootIsProvider(r, base))) &&
+        ui !== pi &&
+        !r.bareAll.has(providerTag)
+      ) {
+        consumers.add(consumer.componentName);
+      }
+    });
+    provider ??= ref;
+  }
+  return { consumers, provider };
+}
+
+/**
+ * Order a component's wrap list OUTERmost-first so the nest is correct. The
+ * emitter opens refs in list order and closes them in reverse, so refs[0] is
+ * the outermost. A provider's own body runs between its open and close, so
+ * every provider ITS requirements name must sit OUTSIDE it: if X requires Y,
+ * Y precedes X. The closure that feeds the list already makes it closed under
+ * requirements, so a required Y is always present to order against. Ties keep
+ * the historical alphabetical order, so a list whose providers owe nothing to
+ * one another renders byte-identical to before; a requirement cycle (no valid
+ * nest — the app is broken at that mount) falls back to that same order and
+ * fails red, which is the honest answer.
+ */
+function orderOutermostFirst(
+  refs: ProviderRef[],
+  reqs: Map<string, Map<string, ProviderRef>>,
+): ProviderRef[] {
+  const byName = [...refs].sort((a, b) =>
+    a.componentName < b.componentName ? -1 : a.componentName > b.componentName ? 1 : 0,
+  );
+  if (refs.length < 2) return byName;
+  const pos = new Map(refs.map((r, i) => [provKey(r), i]));
+  const inList = (k: string) => pos.has(k);
+  // indeg[X] = how many in-list providers X requires (each must come before X).
+  const indeg = new Map<string, number>();
+  const dependents = new Map<string, string[]>(); // Y -> [X that require Y]
+  for (const r of refs) indeg.set(provKey(r), 0);
+  for (const r of refs) {
+    const k = provKey(r);
+    for (const y of reqs.get(k)?.keys() ?? []) {
+      if (!inList(y)) continue;
+      indeg.set(k, (indeg.get(k) ?? 0) + 1);
+      let arr = dependents.get(y);
+      if (!arr) {
+        arr = [];
+        dependents.set(y, arr);
+      }
+      arr.push(k);
+    }
+  }
+  const out: ProviderRef[] = [];
+  const nextReady = (): ProviderRef | undefined => {
+    const avail = refs
+      .filter((r) => (indeg.get(provKey(r)) ?? 0) === 0 && !out.includes(r))
+      .sort((a, b) =>
+        a.componentName < b.componentName ? -1 : a.componentName > b.componentName ? 1 : 0,
+      );
+    return avail[0];
+  };
+  while (out.length < refs.length) {
+    const next = nextReady();
+    if (next === undefined) break; // a requirement cycle: no valid nest
+    out.push(next);
+    const k = provKey(next);
+    for (const d of dependents.get(k) ?? []) {
+      indeg.set(d, (indeg.get(d) ?? 1) - 1);
+    }
+  }
+  if (out.length < refs.length) return byName; // cycle: fall back to alphabetical
+  return out;
+}
+
+/** `${filePath}::${componentName}` → providers to mount around that component. */
+export async function deriveContextProviderWraps(
+  trees: ComponentTree[],
+  cache: SourceFileCache,
+  shims?: (c: { info: { filePath: string } }) => LibraryProviderShim[],
+): Promise<Map<string, ProviderRef[]>> {
+  const flat = flattenTrees(trees);
+  // parseFile is per-file work the sweep's cache already pays for; failures to
+  // read a resolved file skip silently — derivation is opportunistic. Hook
+  // modules often carry no component at all (nakama's use-auth.ts is exactly
+  // one), so the no-component throw must not erase their import tables.
+  const parse = async (file: string) => {
+    try {
+      return await parseFile(file, cache, { tolerateNoComponents: true });
+    } catch {
+      return undefined;
+    }
+  };
+  const parsedCache = new Map<string, ParsedFile | undefined>();
+  const parseOnce = async (file: string) => {
+    let p = parsedCache.get(file);
+    if (p === undefined && !parsedCache.has(file)) {
+      p = await parse(file);
+      parsedCache.set(file, p);
+    }
+    return p;
+  };
+  // Synthetic render edges (the dynamic-render rule below): component key →
+  // the components a project-hook value hands it. Merged into `edges` before
+  // the closure so the worklist closes them like any render edge.
+  const synthEdges = new Map<string, Set<string>>();
+  const nsCache = new Map<string, NamespaceFacts>();
+  const nsOnce = async (file: string) => {
+    let f = nsCache.get(file);
+    if (!f) {
+      const parsed = await parseOnce(file);
+      f = parsed ? namespaceFacts(parsed) : { consumers: new Set<string>() };
+      nsCache.set(file, f);
+    }
+    return f;
+  };
+  const ctxCache = new Map<string, CtxFacts>();
+  const ctxOnce = (parsed: ParsedFile): CtxFacts => {
+    let f = ctxCache.get(parsed.filePath);
+    if (!f) {
+      f = ctxFactsOf(parsed);
+      ctxCache.set(parsed.filePath, f);
+    }
+    return f;
+  };
+
+  // The cross-file context join. Hook and provider need not share a file:
+  // nakama's `useAuth` reads `AuthContext` imported from `auth-context-shared`,
+  // and `AuthProvider` renders `<AuthContext.Provider>` from `auth-context.tsx`
+  // — the context object is the join key, so resolve each mention to a
+  // (module, exported-name) pair and index every component that renders one.
+  const resolver = new ModuleResolver();
+
+  // Dynamic render from a project hook. devtools' ContentPanel does
+  // `const { Component } = useTabs()` and renders `<Component />`: the tag is
+  // an identifier the body binds from a project hook's return, so walkChildren
+  // has no import to resolve, no render edge exists, and the closure has
+  // nothing to close — the registry values include PageTab, whose own spec
+  // gets its data router while the spec that mounts it through the dynamic
+  // element dies on useMatches. The rule: every component the hook's values
+  // can hand out is owed by the component exactly like a statically rendered
+  // child.
+  //
+  // Bounded on purpose: the hook's file, then one import hop inside it, depth
+  // two inside a definition (an array of objects whose value is an arrow
+  // returning JSX — the registry shape), sixteen components. Past the budget
+  // the walk drops out and the shape stays a hole, the way the barrel hands
+  // issue #117 documents.
+  const dynCache = new Map<string, Promise<{ file: string; componentName: string }[]>>();
+  /** Every descendant of `node`, depth first: the public compiler API walks
+   *  one level only, and the rule below needs the whole hook and component
+   *  bodies. */
+  const eachDescendant = (node: ts.Node, visit: (n: ts.Node) => void): void => {
+    ts.forEachChild(node, (child) => {
+      visit(child);
+      eachDescendant(child, visit);
+    });
+  };
+  /** The hook's body node in `sf`: a function declaration or a const arrow,
+   *  the two shapes ctxFactsOf's local-hook collection matches. */
+  const hookBodyOf = (sf: ts.SourceFile, name: string): ts.Node | undefined => {
+    for (const stmt of sf.statements) {
+      if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === name && stmt.body) return stmt.body;
+      if (!ts.isVariableStatement(stmt)) continue;
+      for (const d of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || d.name.text !== name) continue;
+        let init = d.initializer;
+        while (init && ts.isParenthesizedExpression(init)) init = init.expression;
+        if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init)))
+          return init.body ?? init;
+      }
+    }
+    return undefined;
+  };
+  /** The (file, name) a component mention in `p` names: a local declaration
+   *  first, then one value-import hop (the registry shape: the tab file
+   *  renders <PageTab /> imported from its own module). A mention that is
+   *  neither resolves to nothing. */
+  const componentRefOf = async (
+    p: ParsedFile,
+    name: string,
+  ): Promise<{ file: string; componentName: string } | undefined> => {
+    if (p.components.some((u) => u.componentName === name))
+      return { file: p.filePath, componentName: name };
+    const b = p.imports.get(name);
+    if (!b || b.isTypeOnly) return undefined;
+    const target = resolver.resolve(b.specifier, p.filePath);
+    if (!target) return undefined;
+    const tp = await parseOnce(target);
+    const exported = b.importedName ?? name;
+    if (tp?.components.some((u) => u.componentName === exported))
+      return { file: target, componentName: exported };
+    return undefined;
+  };
+  /** Follow one definition initializer for component mentions, on a depth
+   *  budget: array and object members step in, arrow/function bodies do not,
+   *  and a JSX tag or plain identifier is collected wherever it appears
+   *  within budget. `add` resolves the mention to a (file, name). */
+  const collectAsync = async (
+    node: ts.Node | undefined,
+    file: ParsedFile,
+    depth: number,
+    add: (name: string, inFile: ParsedFile) => Promise<void>,
+  ): Promise<void> => {
+    if (!node || depth < 0) return;
+    // `as const` / `satisfies` / parens name the same value one layer down —
+    // devtools' registry is `[...] as const` — so unwrap without paying depth.
+    if (
+      ts.isAsExpression(node) ||
+      ts.isSatisfiesExpression(node) ||
+      ts.isParenthesizedExpression(node)
+    )
+      return collectAsync(node.expression, file, depth, add);
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tag = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName;
+      if (ts.isIdentifier(tag) && /^[A-Z]/.test(tag.text)) await add(tag.text, file);
+      return;
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+      for (const el of node.elements) await collectAsync(el, file, depth - 1, add);
+      return;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      for (const prop of node.properties) {
+        // A shorthand property's initializer IS its name: { component: X }
+        // and { component: X } both name the same mention.
+        const value = ts.isPropertyAssignment(prop)
+          ? prop.initializer
+          : ts.isShorthandPropertyAssignment(prop)
+            ? prop.name
+            : undefined;
+        if (value) await collectAsync(value, file, depth - 1, add);
+      }
+      return;
+    }
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+      await collectAsync(node.body, file, depth, add);
+      return;
+    }
+    if (ts.isBlock(node)) {
+      for (const stmt of node.statements) {
+        if (ts.isReturnStatement(stmt) && stmt.expression)
+          await collectAsync(stmt.expression, file, depth, add);
+      }
+      return;
+    }
+    if (ts.isIdentifier(node) && /^[A-Z]/.test(node.text)) await add(node.text, file);
+  };
+  /** The components a hook's values can hand out, keyed by (file, hook
+   *  name): the hook body's own JSX, plus the definitions its value
+   *  identifiers import — the registry the hook selects from. Cached: a hook
+   *  shared by several components parses once, and the slice bounds the
+   *  fan-out a pathological registry could otherwise give the edges. */
+  const dynamicRenderablesOf = async (
+    file: string,
+    hookName: string,
+  ): Promise<{ file: string; componentName: string }[]> => {
+    const key = `${file}::${hookName}`;
+    let p = dynCache.get(key);
+    if (!p) {
+      p = (async () => {
+        const parsed = await parseOnce(file);
+        if (!parsed) return [];
+        const body = hookBodyOf(parsed.sourceFile, hookName);
+        if (!body) return [];
+        const found = new Map<string, { file: string; componentName: string }>();
+        const add = async (name: string, inFile: ParsedFile): Promise<void> => {
+          const r = await componentRefOf(inFile, name);
+          if (r) found.set(`${r.file}::${r.componentName}`, r);
+        };
+        eachDescendant(body, (n) => {
+          const tag =
+            ts.isJsxElement(n) && ts.isIdentifier(n.openingElement.tagName)
+              ? n.openingElement.tagName
+              : ts.isJsxSelfClosingElement(n) && ts.isIdentifier(n.tagName)
+                ? n.tagName
+                : undefined;
+          if (tag && /^[A-Z]/.test(tag.text)) void add(tag.text, parsed);
+        });
+        // The value identifiers the body holds: the registry the hook selects
+        // from, one file hop into each imported definition. A hop is paid per
+        // TARGET file — the import table maps local names, and two names from
+        // one module are the same hop.
+        const hopped = new Set<string>();
+        const hopTargets = new Map<string, string>();
+        eachDescendant(body, (n) => {
+          if (!ts.isIdentifier(n)) return;
+          const b = parsed.imports.get(n.text);
+          if (!b || b.isTypeOnly) return;
+          const target = resolver.resolve(b.specifier, parsed.filePath);
+          if (!target || hopped.has(target)) return;
+          hopped.add(target);
+          hopTargets.set(target, b.importedName ?? n.text);
+        });
+        for (const [target, name] of hopTargets) {
+          const tp = await parseOnce(target);
+          if (!tp) continue;
+          // The top-level definition of the imported name; a barrel that only
+          // re-exports it declares nothing and ends the walk.
+          let def: ts.Node | undefined;
+          for (const stmt of tp.sourceFile.statements) {
+            if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === name && stmt.body)
+              def = stmt.body;
+            else if (ts.isVariableStatement(stmt)) {
+              for (const d of stmt.declarationList.declarations) {
+                if (ts.isIdentifier(d.name) && d.name.text === name && d.initializer)
+                  def = d.initializer;
+              }
+            }
+            if (def) break;
+          }
+          if (def) await collectAsync(def, tp, 2, add);
+        }
+        return [...found.values()].slice(0, 16);
+      })();
+      dynCache.set(key, p);
+    }
+    return p;
+  };
+
+  const ctxKeyOf = (file: string, ref: RawCtxRef): string | undefined => {
+    if (!ref.module) return `${file}::${ref.name}`;
+    const resolved = resolver.resolve(ref.module, file);
+    return resolved ? `${resolved}::${ref.name}` : undefined;
+  };
+  const supplierByKey = new Map<string, { file: string; componentName: string }[]>();
+  for (const file of new Set(flat.map((c) => c.info.filePath))) {
+    const parsed = await parseOnce(file);
+    if (!parsed) continue;
+    for (const [componentName, ref] of ctxOnce(parsed).suppliesRaw) {
+      const key = ctxKeyOf(file, ref);
+      if (!key) continue;
+      const arr = supplierByKey.get(key);
+      if (arr) arr.push({ file, componentName });
+      else supplierByKey.set(key, [{ file, componentName }]);
+    }
+  }
+
+  // The convention index, for hooks that arrive from a BARE module. When a
+  // component's hook comes from node_modules (never parsed) the context join
+  // above has no key: the context object the hook reads lives in the library,
+  // so no project file mentions it. What project files DO mention is the
+  // app's own wrapper — saleor's `useTheme` comes from `@saleor/macaw-ui-next`,
+  // and the app's exported `ThemeProvider` (src/theme/provider.tsx) renders
+  // macaw's `ThemeProvider`, imported from that very module. Index every
+  // exported component by (name, module of a binding its body renders): the
+  // convention name plus the same-module binding is the pairing the context
+  // object would have supplied. All three conjuncts — exported, named per the
+  // hook's convention, rendering a binding from the hook's own module — or
+  // nothing; a `ThemeProvider` that renders some other kit's provider must
+  // not catch a hook from a different one.
+  const conventionSuppliers = new Map<string, { file: string; componentName: string }[]>();
+  for (const file of new Set(flat.map((c) => c.info.filePath))) {
+    const parsed = await parseOnce(file);
+    if (!parsed) continue;
+    const facts = ctxOnce(parsed);
+    for (const u of parsed.components) {
+      if (u.exportKind === "none") continue;
+      for (const tag of facts.tagsByFn.get(u.componentName) ?? []) {
+        const b = parsed.imports.get(tag);
+        if (!b || b.isTypeOnly || b.specifier.startsWith(".") || b.specifier.startsWith("/"))
+          continue;
+        const key = `${u.componentName}::${b.specifier}`;
+        const arr = conventionSuppliers.get(key);
+        if (arr) arr.push({ file, componentName: u.componentName });
+        else conventionSuppliers.set(key, [{ file, componentName: u.componentName }]);
+      }
+    }
+  }
+
+  // compKey → provKey → ref. A Map, not a Set: the closure below merges along
+  // component edges and the dedupe is by provider identity.
+  const reqs = new Map<string, Map<string, ProviderRef>>();
+  const addReq = (compKey: string, ref: ProviderRef) => {
+    if (provKey(ref) === compKey) return; // never wraps itself
+    let m = reqs.get(compKey);
+    if (!m) {
+      m = new Map();
+      reqs.set(compKey, m);
+    }
+    m.set(provKey(ref), ref);
+  };
+
+  for (const c of flat) {
+    const compKey = providerKey(c.info);
+    for (const hook of new Set((c.info.hookDetails ?? []).map((h) => h.name))) {
+      if (!/^use[A-Z]/.test(hook) || CORE_HOOKS.has(hook)) continue;
+      // Where does the hook come from? Imported → its module; otherwise the
+      // component's own file (the co-located shadcn shape). An alias
+      // (`import { useSidebar as useSb }`) binds a local name the call site
+      // uses, but the provider is named after the MODULE-side hook.
+      let sourceFile = c.info.filePath;
+      let moduleSide = hook;
+      let hookSpec: string | undefined;
+      for (const mi of c.info.moduleImports ?? []) {
+        if (mi.isTypeOnly) continue;
+        const i = mi.names.indexOf(hook);
+        if (i === -1) continue;
+        hookSpec = mi.specifier;
+        if (mi.resolvedPath) {
+          sourceFile = mi.resolvedPath;
+          moduleSide = mi.importedNames?.[i] ?? hook;
+        }
+        // A bare library import binds the name too — but there is no file to
+        // parse, so the derivation stays on the component's own file and the
+        // shim table below decides.
+        break;
+      }
+      if (!moduleSide.startsWith("use")) continue; // aliased to a non-hook name
+      const candidate = `${moduleSide.slice(3)}Provider`;
+      const parsed = await parseOnce(sourceFile);
+      let unit = parsed?.components.find((u) => u.componentName === candidate);
+      let providerFile = sourceFile;
+      if (parsed && (!unit || unit.exportKind === "none")) {
+        // The convention missed — find the component that supplies the
+        // context this hook actually reads, however it is named.
+        const facts = ctxOnce(parsed);
+        const supplied = facts.providerByHook.get(moduleSide);
+        if (supplied) unit = parsed.components.find((u) => u.componentName === supplied);
+        // Still nothing, and the pairing lives across files: join the context
+        // objects this hook reads against the components that render them.
+        if (!unit) {
+          for (const ref of facts.readsRaw.get(moduleSide) ?? []) {
+            const key = ctxKeyOf(sourceFile, ref);
+            if (!key) continue;
+            for (const cand of supplierByKey.get(key) ?? []) {
+              const candParsed = await parseOnce(cand.file);
+              const u = candParsed?.components.find((x) => x.componentName === cand.componentName);
+              if (u && u.exportKind !== "none" && !u.isAsync && providerMountsBare(u)) {
+                unit = u;
+                providerFile = cand.file;
+                break;
+              }
+            }
+            if (unit) break;
+          }
+        }
+        // The bare-module convention. The hook's own module is in node_modules
+        // (never parsed), so neither lookup above can see the pairing: the
+        // context object lives in the library. The app's wrapper, however, is
+        // project code — an exported component named per the hook's convention
+        // that renders a binding imported from the very module the hook came
+        // from (saleor's `useTheme` ← `@saleor/macaw-ui-next`, supplied by
+        // the app's own `ThemeProvider` around macaw's).
+        if (
+          !unit &&
+          hookSpec &&
+          sourceFile === c.info.filePath &&
+          !hookSpec.startsWith(".") &&
+          !hookSpec.startsWith("/")
+        ) {
+          for (const sup of conventionSuppliers.get(`${candidate}::${hookSpec}`) ?? []) {
+            const supParsed = await parseOnce(sup.file);
+            const u = supParsed?.components.find((x) => x.componentName === sup.componentName);
+            if (u && u.exportKind !== "none" && !u.isAsync && providerMountsBare(u)) {
+              unit = u;
+              providerFile = sup.file;
+              break;
+            }
+          }
+        }
+      }
+      if (unit && unit.exportKind !== "none" && !unit.isAsync && providerMountsBare(unit)) {
+        addReq(compKey, {
+          componentName: unit.componentName,
+          filePath: providerFile,
+          exportKind: unit.exportKind,
+          exportedAs: unit.exportedAs,
+        });
+      } else if (!unit) {
+        // Nothing in the project pairs with this hook — a library context
+        // does. Either the hook is imported from the library itself, or the
+        // module-side hook is a project WRAPPER whose body calls one —
+        // possibly through more wrappers across files: McpServerDialog →
+        // useMcpServerDialogState → useMcpServerDetailQuery → useQuery, and
+        // the component never names the library at all.
+        const libs = new Set<string>(hookSpec ? [hookSpec] : []);
+        // Which LIBRARY hooks the wrapper chain actually calls. Two shims can
+        // share a module — react-router's MemoryRouter wrap and its data wrap
+        // are the same specifier — so "the chain reached a shimmed module"
+        // cannot pick between them: the table's order did, and the first entry
+        // won. VersionDropdown asked for MemoryRouter while dying of
+        // useRouteLoaderData.
+        const libHooks = new Set<string>();
+        const seenHooks = new Set<string>();
+        // Convention providers the chain reached through a BARE module: a
+        // wrapper that calls a library hook has no file to walk, but the app
+        // may still ship the convention provider for it (SaleorLogo ←
+        // `@dashboard/theme` ← useMacawTheme ← `@saleor/macaw-ui-next`,
+        // supplied by the app's own ThemeProvider).
+        const convRefs: { file: string; componentName: string }[] = [];
+        const convSeen = new Set<string>();
+        const walkLibs = async (file: string, name: string): Promise<void> => {
+          const key = `${file}::${name}`;
+          if (seenHooks.has(key)) return;
+          seenHooks.add(key);
+          const p = await parseOnce(file);
+          if (!p) return;
+          const f = ctxOnce(p);
+          for (const m of f.libsByHook.get(name) ?? []) libs.add(m);
+          for (const called of f.callsByHook.get(name) ?? []) {
+            if (called === name) continue;
+            const b = p.imports.get(called);
+            if (!b || b.isTypeOnly) continue;
+            const side = b.importedName ?? called;
+            for (const s of LIBRARY_SHIMS) {
+              if (shimModules(s).includes(b.specifier) && s.hooks.includes(side)) {
+                libHooks.add(side);
+              }
+            }
+            const target = resolver.resolve(b.specifier, file);
+            if (target) {
+              await walkLibs(target, side);
+            } else if (
+              /^use[A-Z]/.test(side) &&
+              !b.specifier.startsWith(".") &&
+              !b.specifier.startsWith("/")
+            ) {
+              // The call dies at a bare LIBRARY module — node_modules is never
+              // walked — but the app's own wrapper for it, if it exists, is
+              // project code indexed by (convention name, that very module).
+              // The key uses the MODULE-side name: `import { useTheme as
+              // useMacawTheme }` asks for ThemeProvider, not MacawThemeProvider.
+              for (const sup of conventionSuppliers.get(
+                `${side.slice(3)}Provider::${b.specifier}`,
+              ) ?? []) {
+                const ck = `${sup.file}::${sup.componentName}`;
+                if (!convSeen.has(ck)) {
+                  convSeen.add(ck);
+                  convRefs.push(sup);
+                }
+              }
+            }
+          }
+          // The barrel hop. A re-export table declares nothing, so a chain that
+          // reaches one ends there — and in a Feature-Sliced app almost every
+          // import reaches one. ton-console's CurrencyRate imports useRateQuery
+          // from `src/entities/rates`, which is `export * from './model'`,
+          // whose index is `export { useRateQuery } from './queries'`, and
+          // queries.ts is where useQuery is called. The chain stopped at the
+          // first barrel and the component got no provider: 87
+          // `No QueryClient set` failures in that one app. The named form is
+          // exact so it goes first; `export *` only says "ask the target", so
+          // it is tried when no named hop carries the name. Precision survives
+          // the fan-out either way, because libs are only ever recorded from a
+          // file that DECLARES the hook.
+          //
+          // One shape the hop cannot carry: a barrel handing the LIBRARY itself
+          // along — `export { useQuery } from '@tanstack/react-query'`, or the
+          // star form. The specifier is bare and the resolver refuses it on
+          // purpose (node_modules is never walked), so the chain ends with the
+          // library unrecorded and the component unwrapped. Measured against
+          // every corpus app (2026-10-22): the only such barrels are zudoku's,
+          // in a package its sweep does not cover — documented as the family's
+          // last hole in issue #117, not fixed without a witness to exercise
+          // it.
+          if (f.declaredHooks.has(name)) return;
+          const hops = f.reexportedHooks.get(name) ?? [];
+          for (const hop of hops) {
+            const target = resolver.resolve(hop.specifier, file);
+            if (target) await walkLibs(target, hop.imported);
+          }
+          if (hops.length > 0) return;
+          for (const spec of f.starSpecifiers) {
+            const target = resolver.resolve(spec, file);
+            if (target) await walkLibs(target, name);
+          }
+        };
+        if (parsed) await walkLibs(sourceFile, moduleSide);
+        const candidates = (shims?.(c) ?? []).filter(
+          (s) =>
+            shimModules(s).some((m) => libs.has(m)) &&
+            (shimModules(s).includes(hookSpec ?? "")
+              ? s.hooks.includes(moduleSide)
+              : libHooks.size === 0 || s.hooks.some((h) => libHooks.has(h))),
+        );
+        // Of the shims that fit, the one that makes another redundant wins: a
+        // wrapper calling useNavigate AND useLoaderData needs the data router,
+        // which serves navigation too, not a wrap the mount will shadow.
+        const shim =
+          candidates.find(
+            (s) =>
+              !candidates.some(
+                (other) =>
+                  other !== s && SUPERSEDED_BY.get(s.componentName) === other.componentName,
+              ),
+          ) ?? candidates[0];
+        if (shim) {
+          addReq(compKey, {
+            componentName: shim.componentName,
+            filePath: shim.filePath,
+            exportKind: "named",
+          });
+        }
+        for (const sup of convRefs) {
+          const supParsed = await parseOnce(sup.file);
+          const u = supParsed?.components.find((x) => x.componentName === sup.componentName);
+          if (u && u.exportKind !== "none" && !u.isAsync && providerMountsBare(u)) {
+            addReq(compKey, {
+              componentName: u.componentName,
+              filePath: sup.file,
+              exportKind: u.exportKind,
+              exportedAs: u.exportedAs,
+            });
+          }
+        }
+      }
+    }
+    // The library COMPONENT ladder: rendering a provider-gated component asks
+    // for that library's provider exactly like calling its hook does. This was
+    // the gap saleor-dashboard fell into — components that render
+    // <FormattedMessage> and never name `useIntl`, so the hook walk above found
+    // nothing to key on and the mount died on the missing provider.
+    const own = await parseOnce(c.info.filePath);
+    const ownTags = own ? ctxOnce(own).tagsByFn.get(c.info.componentName) : undefined;
+    if (own && ownTags) {
+      for (const s of shims?.(c) ?? []) {
+        if (!s.components || s.components.length === 0) continue;
+        if (reqs.get(compKey)?.has(`${s.filePath}::${s.componentName}`)) continue;
+        for (const tag of ownTags) {
+          const b = own.imports.get(tag);
+          if (!b || b.isTypeOnly || !shimModules(s).includes(b.specifier)) continue;
+          if (!s.components.includes(b.importedName ?? tag)) continue;
+          addReq(compKey, {
+            componentName: s.componentName,
+            filePath: s.filePath,
+            exportKind: "named",
+          });
+          break;
+        }
+      }
+    }
+    // Dynamic render from a project hook: <Component /> whose tag the body
+    // binds by destructuring a project hook's return. devtools' ContentPanel
+    // gets useTabs' chosen tab this way, and the registry's values are then
+    // owed exactly like statically rendered children — with the edge, PageTab's
+    // data router reaches the spec that mounts it through the dynamic element.
+    // Only shorthand/plain bindings count: an alias or a default is a shape
+    // the rule declines rather than guesses at, and a prop of the same shape
+    // stays the spec's business.
+    if (own) {
+      const unit = own.components.find((u) => u.componentName === c.info.componentName);
+      const body = unit?.bodyNode;
+      if (body) {
+        const boundToHook = new Map<string, string>(); // bound name -> hook local name
+        eachDescendant(body, (m) => {
+          if (!ts.isVariableDeclaration(m) || !m.initializer) return;
+          const init = ts.isAwaitExpression(m.initializer)
+            ? m.initializer.expression
+            : m.initializer;
+          if (
+            !ts.isCallExpression(init) ||
+            !ts.isIdentifier(init.expression) ||
+            !/^use[A-Z]/.test(init.expression.text) ||
+            CORE_HOOKS.has(init.expression.text)
+          )
+            return;
+          const hookLocal = init.expression.text;
+          if (ts.isObjectBindingPattern(m.name)) {
+            for (const el of m.name.elements) {
+              if (
+                ts.isIdentifier(el.name) &&
+                !el.propertyName &&
+                !el.initializer &&
+                /^[A-Z]/.test(el.name.text)
+              )
+                boundToHook.set(el.name.text, hookLocal);
+            }
+          } else if (ts.isIdentifier(m.name) && /^[A-Z]/.test(m.name.text)) {
+            boundToHook.set(m.name.text, hookLocal);
+          }
+        });
+        if (boundToHook.size > 0) {
+          const rendered = new Set<string>();
+          eachDescendant(body, (n) => {
+            const tag = ts.isJsxOpeningElement(n)
+              ? n.tagName
+              : ts.isJsxSelfClosingElement(n)
+                ? n.tagName
+                : undefined;
+            if (tag && ts.isIdentifier(tag) && /^[A-Z]/.test(tag.text)) rendered.add(tag.text);
+          });
+          for (const tag of rendered) {
+            const hookLocal = boundToHook.get(tag);
+            if (!hookLocal) continue;
+            let sourceFile: string | undefined;
+            const b = own.imports.get(hookLocal);
+            if (b && !b.isTypeOnly) {
+              sourceFile = resolver.resolve(b.specifier, own.filePath);
+              if (!sourceFile) continue; // bare module — no project body to walk
+            } else sourceFile = own.filePath; // co-located with the component
+            for (const r of await dynamicRenderablesOf(sourceFile, hookLocal)) {
+              let s = synthEdges.get(compKey);
+              if (!s) {
+                s = new Set();
+                synthEdges.set(compKey, s);
+              }
+              s.add(`${r.file}::${r.componentName}`);
+            }
+          }
+        }
+      }
+    }
+    const ns = await nsOnce(c.info.filePath);
+    if (ns.provider && ns.consumers.has(c.info.componentName)) {
+      addReq(compKey, ns.provider);
+    }
+  }
+
+  // Transitive requirement: a mount fails at the ancestor whose untouched leaf
+  // threw, so what a mount must satisfy reaches past its own body. Two ways in:
+  // the analysis trees record what RENDERS what (a leaf's providers owed by its
+  // ancestor), and a provider that is itself wrapped OWES its own requirements
+  // to whoever mounts it. Both are monotonic merges by provider identity, so
+  // one fixpoint over both closes the graph — cycles converge because
+  // self-references drop.
+  const edges = new Map<string, Set<string>>();
+  const walk = (t: ComponentTree): void => {
+    const pk = providerKey(t.entry);
+    for (const c of t.children) {
+      const ck = providerKey(c.entry);
+      if (ck !== pk) {
+        let s = edges.get(pk);
+        if (!s) {
+          s = new Set();
+          edges.set(pk, s);
+        }
+        s.add(ck);
+      }
+      walk(c);
+    }
+  };
+  for (const t of trees) walk(t);
+  // The dynamic-render rule above recorded render edges the analysis trees
+  // cannot see — a dynamic tag has no import to resolve and no static tag to
+  // walk. Merged in before the worklist, the closure closes them like any
+  // render edge: ordering, supersedence and cycle handling stay untouched.
+  for (const [pk, kids] of synthEdges) {
+    let s = edges.get(pk);
+    if (!s) {
+      s = new Set();
+      edges.set(pk, s);
+    }
+    for (const ck of kids) s.add(ck);
+  }
+  // The closure runs as a WORKLIST, not a level pass: a wrapped provider may
+  // owe several hops further (it renders a child, that child wraps another
+  // provider, …), and a level pass moves only one hop — on ton-console's page
+  // trees that is thousands of passes before the graph settles. Instead: the
+  // queue seeds with every component that already owes something and its
+  // render parents, and every time a component's requirements GROW, the
+  // components that owe it — the ones that render it, and the ones that now
+  // wrap it (a wrapped provider's new requirement is owed by its wrapper too)
+  // — take a turn. Each (component, provider) pair is added once, so the work
+  // is linear in the number of pairs, and a cycle is paid for once as well.
+  const owedTo = new Map<string, Set<string>>(); // key -> components that render it
+  for (const [pk, kids] of edges) {
+    for (const ck of kids) {
+      let s = owedTo.get(ck);
+      if (!s) {
+        s = new Set();
+        owedTo.set(ck, s);
+      }
+      s.add(pk);
+    }
+  }
+  const queue: string[] = [];
+  const queued = new Set<string>();
+  const enqueue = (k: string) => {
+    if (!queued.has(k)) {
+      queued.add(k);
+      queue.push(k);
+    }
+  };
+  // Seed: every component that OWES something. A component with requirements
+  // owes them to whoever renders it (the render edges recorded above), and it
+  // owes its wrapped providers' requirements to itself. A component with no
+  // requirements of its own is seeded only when a dependency grows.
+  for (const pk of reqs.keys()) {
+    enqueue(pk);
+    for (const owner of owedTo.get(pk) ?? []) enqueue(owner);
+  }
+  let qi = 0;
+  while (qi < queue.length) {
+    const pk = queue[qi];
+    qi += 1;
+    if (pk === undefined) continue;
+    queued.delete(pk);
+    // A render parent can be queued before it owes anything of its own, so
+    // the map may not exist yet — create it the way addReq does, and let the
+    // empty case fall out in `out` below.
+    let mine = reqs.get(pk);
+    if (!mine) {
+      mine = new Map();
+      reqs.set(pk, mine);
+    }
+    // What pk owes: the components it RENDERS (the tree edges above) and the
+    // providers it WRAPS — its own requirements. The second is the rule a
+    // wrapper owes its payload: ProjectProvider mounts INSIDE the component,
+    // and its body calls useUserQuery -> useQuery, so the component's spec
+    // needs the QueryClientProvider that ProjectProvider's own spec has. A
+    // shim ref names a generated file no component analysis carries, so its
+    // "own requirements" look up empty and it is a no-op.
+    const deps = new Set<string>(edges.get(pk) ?? []);
+    for (const key of mine.keys()) deps.add(key);
+    deps.delete(pk);
+    const added: string[] = [];
+    for (const dk of deps) {
+      const dep = reqs.get(dk);
+      if (!dep) continue;
+      for (const [key, ref] of dep) {
+        // A dependency that wraps pk itself is a cycle: addReq would no-op
+        // the self-pair, but recording it as a new wrap edge re-enqueues pk
+        // forever. Self-references drop, as they always have.
+        if (key === pk || mine.has(key)) continue;
+        addReq(pk, ref);
+        added.push(key);
+        // pk now WRAPS key: record it, or pk's dependents never learn that
+        // pk owes key's requirements.
+        let owed = owedTo.get(key);
+        if (!owed) {
+          owed = new Set();
+          owedTo.set(key, owed);
+        }
+        owed.add(pk);
+      }
+    }
+    if (added.length === 0) continue;
+    // pk must pull each newly wrapped provider's OWN requirements, and every
+    // component that renders pk (or now wraps it) must pull pk's new ones.
+    enqueue(pk);
+    for (const owner of owedTo.get(pk) ?? []) enqueue(owner);
+  }
+
+  const out = new Map<string, ProviderRef[]>();
+  for (const [compKey, m] of reqs) {
+    // The closure completed the SET; the nest needs an ORDER. A provider's
+    // body runs between its own open and close, so everything its requirements
+    // name must sit OUTSIDE it: if X requires Y, Y precedes X. Untied, the
+    // historical alphabetical order stands, so a spec whose providers owe
+    // nothing to each other renders exactly as it did.
+    const refs = orderOutermostFirst([...m.values()], reqs);
+    // One provider can make another redundant (LibraryShimSpec.supersedes): the
+    // data router already serves every hook and tag MemoryRouter does, so a
+    // component needing both gets one wrap, not a shadowed one inside the other.
+    const present = new Set(refs.map((r) => r.componentName));
+    const kept = refs.filter((r) => {
+      const by = SUPERSEDED_BY.get(r.componentName);
+      return by === undefined || !present.has(by);
+    });
+    if (kept.length > 0) {
+      out.set(compKey, kept);
+    }
+  }
+  return out;
+}