obsidian-vault/work/wiki/apple-browsers/import-hygiene.md

source, confidence, namespace, last_synced, alwaysApply

source	confidence	namespace	last_synced	alwaysApply
~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/import-hygiene.mdc	0.9	work	2026-04-28	true

Import Hygiene & Preview-Only Imports

Purpose

Prevent accidental or unrequested import churn that causes build/lint issues and diffs unrelated to the task. Ensure SwiftUI is only imported where required (e.g., #Preview blocks) and avoid touching existing imports unless strictly necessary.

Rules (Always Apply)

1. Do not change imports unless:

   • A new symbol is introduced that the compiler cannot resolve without the import
   • An existing import is provably unused and removal is part of the explicit task scope
   • The change resolves a red compiler error you introduced in this edit

2. Keep platform/framework imports minimal and local:

   • Prefer import AppKit for macOS UI code
   • Prefer import UIKit for iOS UI code
   • Do not add import SwiftUI to AppKit/UIKit view controllers unless they embed SwiftUI.

3. Scope SwiftUI to previews:

   • Only import SwiftUI inside #if DEBUG blocks for #Preview declarations
   • Example: See swiftui-preview-import.swift

4. Keep Shared Modules stable:

   • Do not remove import Common or other project modules unless a dedicated cleanup task
   • If a module is required elsewhere in the file, do not move or duplicate it

5. Lint & Build first, then adjust:

   • If a file shows missing-types errors after your edits (e.g., Cannot find type 'FireproofDomains'), prefer adding the specific missing import required for those existing symbols
   • Avoid speculative imports

6. No import reordering for style-only reasons unless the repository enforces it via formatter

Rationale

• Unnecessary import edits generate churn and can break platform- or target-specific build settings
• Scoping SwiftUI to previews avoids accidental framework inclusion and linking in non-preview code paths

Examples

• CORRECT (AppKit-only controller): See appkit-only-controller.swift

• CORRECT (preview-only SwiftUI): See preview-only-swiftui.swift

• AVOID: See import-to-avoid.swift

Enforcement Guidance

• During PR review, reject changes that add/remove imports without a clear necessity
• Prefer comments in code review over automated reordering unless enforced by tooling