FUI1003: Import should use the preferred path

What it means

Fragments resolved the imported component to an underlying package export whose approved path is different. The finding evidence names both the imported module and the preferred module.

How to resolve it

Import the component from the preferred path shown in the finding. When a local wrapper is the approved canonical surface, declare it with govern.canonicalBridges: identify the underlying package/export, the local component key and module specifier, and the wrapper's implementationFiles. That scope lets the wrapper implementation import its underlying component without teaching the rest of the app to bypass the wrapper.

To take a whole path out of scope for this rule — a vendored drop, a legacy area you have not migrated — add an exclude glob to the govern.jsx record that raised the finding, or to govern.rules["imports/preferred-path"]. Excluded findings are counted and named with their reason in the run's ignored accounting, so the exemption stays auditable:

govern: {
  jsx: [
    {
      kind: "jsx.importPath.prefer",
      from: "@mui/material",
      to: "@/components",
      severity: "warn",
      exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop, tracked in DS-611" }],
    },
  ],
}

An exclude scopes only the policy that declares it: other rules still run over the same files, and a glob that matches no scanned file is reported as FUI9006 rather than passing as active policy. For an intentional, line-specific exception, place one of the documented directives immediately before the affected statement:

// fragments-allow FUI1003: legacy import migration tracked in DS-611
import { Button } from "@mui/material";

// @fragments-expect-error FUI1003 reason="legacy import migration tracked in DS-611" expires="2026-12-31"
import { Button } from "@mui/material";

See the configuration and suppression reference for the full bridge fields, expiry guidance, and audit commands.

Verify the change

Run npx @usefragments/cli check --changed --format agent, confirm the preferred import or matched suppression appears in the evidence, then run npx @usefragments/cli check --changed --ci.