Skip to main content

FUI1003: Import should use the preferred path

moderate

An import bypasses the component path selected by the active governance contract.

Details

diagnostic
{
  "code": "FUI1003",
  "ruleId": "imports/preferred-path",
  "category": "Canonical Usage",
  "defaultSeverity": "moderate",
  "lifecycle": "experimental",
  "fixAvailable": true,
  "evidenceRequired": true
}

Guidance

## 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:

```ts 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:

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

```ts // @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](/cloud/verdicts#in-source) 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`.

Intentional exception? Use a narrow, reasoned directive from the in-source exception reference.

Next steps

  • RulesThe rules that emit FUI codes.
  • ExceptionsIn-source allows and Cloud exceptions.