55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
---
|
|
source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/import-hygiene.mdc
|
|
confidence: 0.9
|
|
namespace: work
|
|
last_synced: 2026-04-28
|
|
alwaysApply: 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](import-hygiene/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](import-hygiene/appkit-only-controller.swift)
|
|
|
|
- **CORRECT (preview-only SwiftUI):** See [preview-only-swiftui.swift](import-hygiene/preview-only-swiftui.swift)
|
|
|
|
- **AVOID:** See [import-to-avoid.swift](import-hygiene/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
|