swift-code-quality

Swift Code Quality Rules

Full reference: docs/AGENT-GUIDELINES.md → Swift Code Quality Rules.

File Size

When approaching 300 lines: extract cohesive responsibilities into separate files, use extensions in separate files for protocol conformances.

No Singletons in Views or Services

// ❌ BANNED
@Bindable var coordinator = NotchViewCoordinator.shared
let manager = SomeManager.shared

// ✅ REQUIRED — environment injection
@Environment(NotchViewModel.self) private var viewModel
@Environment(\.pluginManager) private var pluginManager

// ✅ REQUIRED — init injection
init(service: SomeServiceProtocol) { ... }

Allowed .shared exceptions: NSWorkspace, NSApplication, URLSession, URLCache, XPCHelperClient, FullScreenMonitor, QLThumbnailGenerator, QLPreviewPanel, NSScreenUUIDCache, SkyLightOperator, DefaultsNotchSettings (injection root only), ScreenDisplayRegistry (system-level screen cache).

No Direct Defaults Access

// ❌ BANNED everywhere except NotchSettings.swift
Defaults[.someSetting]
@Default(.someSetting) var setting

// ✅ REQUIRED
settings.someSetting
@Environment(\.bindableSettings) private var settings

Exception: NotchSettings.swift is the only file allowed direct Defaults access.

Observable State

// ✅ REQUIRED
@Observable
@MainActor
final class SomeViewModel { ... }

// ❌ BANNED
class SomeViewModel: ObservableObject {
    @Published var state: State
}

All UI-related protocols and classes must be @MainActor.

Protocol-Based Services

// Protocol in separate file
protocol SomeServiceProtocol: Sendable {
    func doThing() async throws
}

// Implementation
final class SomeService: SomeServiceProtocol { ... }

Never depend on concrete service types — always use the protocol.

File Organization Order

1. Imports
2. Type declaration + stored properties
3. Initializers
4. Public/internal methods
5. Private methods
6. Extensions (prefer separate files for large protocol conformances)

Commit Checklist Before Submitting Swift Changes

• File stays under 300 lines (if split, both files build)
• No new .shared access in views or services
• No new direct Defaults[.] outside NotchSettings.swift
• New state classes use @Observable @MainActor final class
• New services have a protocol
• bazelisk build //Apps/machNotch:machNotch passes

Codex Invocation

Use this skill for Swift file edits and reviews. Codex does not enforce Claude paths or user-invocable metadata, so the file-scope trigger is preserved in the description.