75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# Repository Guidelines
|
|
|
|
Luma is an XMPP client for iOS, iPadOS, macOS, and watchOS, built with SwiftUI
|
|
and the Martin / MartinOMEMO libraries. The Xcode project is generated from
|
|
`project.yml` by XcodeGen — never edit `Luma.xcodeproj` directly.
|
|
|
|
## Project Structure
|
|
|
|
- `Sources/App/` — iOS/macOS app entry point (`LumaApp.swift`).
|
|
- `Sources/Shared/` — shared code:
|
|
- `Models/` — value types and pure policy enums (`ArchiveSyncPagination`,
|
|
`ChatTypingPolicy`, …) plus the SwiftData `@Model` classes
|
|
(`ChatMessage`, `Conversation`).
|
|
- `UI/` — SwiftUI views; chat/contact lists read SwiftData through
|
|
`@Query` (`MainTabView`, `ChatView`, `ForwardMessageView`); the main
|
|
screen is Telegram-style: an iOS native `TabView` tab bar
|
|
(Контакты/Звонки/Чаты/Настройки) with inline search fields above
|
|
the lists, and a
|
|
macOS Telegram Desktop-style split view (`MainSplitView`: sidebar
|
|
with menu/search/list plus a chat detail pane).
|
|
- `XMPP/` — `XMPPService` (MAM/OMEMO/MUC), `LumaCallEngine`, OMEMO store,
|
|
`LumaOMEMO2Module` (urn:xmpp:omemo:2 wire format: AES-256-CBC + HMAC
|
|
payload, SCE envelope, device/bundle PEP nodes — shares the Double
|
|
Ratchet sessions with the legacy module), `SASLprep` (RFC 4013),
|
|
SCRAM-SHA-512 mechanism, SASL failure observer/messages.
|
|
- `Persistence/` — `ArchiveStore` (per-account SwiftData container),
|
|
`ArchiveMetadataRecord` (durable MAM checkpoint metadata),
|
|
`LegacyArchiveImporter` (one-time legacy JSON snapshot migration),
|
|
preferences.
|
|
- `Services/`, `Security/` — media, notifications, credentials.
|
|
- `Sources/Watch/` — single-target watchOS app.
|
|
- `Tests/` — XCTest unit tests.
|
|
- `Resources/`, `Config/`, `Brand/`, `Docs/` — assets, plists/entitlements,
|
|
icons, architecture/security docs.
|
|
|
|
## Build, Test & Development
|
|
|
|
- `make project` — regenerate `Luma.xcodeproj` from `project.yml`
|
|
(requires `brew install xcodegen`).
|
|
- `make open` — regenerate and open Xcode.
|
|
- `make verify` — run `Scripts/verify.sh`: grep-based structural invariants
|
|
plus an optional simulator build.
|
|
- `make clean` — remove the generated project and DerivedData.
|
|
- `xcodebuild test -project Luma.xcodeproj -scheme Luma \
|
|
-destination 'platform=iOS Simulator,name=iPhone 17 Pro Max'` — build and
|
|
run the test suite.
|
|
|
|
## Coding Style
|
|
|
|
- Swift 5.9; 4-space indentation (set in `project.yml`).
|
|
- UI-facing state is `@MainActor` (`AppModel`, `XMPPService`); keep heavy work
|
|
(OMEMO decryption, media, persistence) off the main actor.
|
|
- Prefer small, pure value types and unit-testable policy enums over inline
|
|
branching.
|
|
- UI strings are Russian; identifiers and code comments are English.
|
|
- No formatter/linter; `Scripts/verify.sh` is the guard — keep its greps in
|
|
sync when you change constants or symbols.
|
|
|
|
## Testing
|
|
|
|
- XCTest with `@testable import Luma`; one file per model/policy
|
|
(e.g., `ArchiveSyncPaginationTests.swift`), methods named `test...`.
|
|
- Unit-test pure logic (policies, pagination, checkpoints); network/UI flows
|
|
are verified manually.
|
|
- When a policy constant changes, update the matching `Tests/*` assertions and
|
|
the `Scripts/verify.sh` guard in the same commit.
|
|
|
|
## Commit & Pull Request
|
|
|
|
- Short, imperative, English subject lines (see `git log`: "mam fixes",
|
|
"fix errors and warnings").
|
|
- CI (`.github/workflows/ios.yml`) runs `xcodebuild test` on push to
|
|
`main`/`develop` and on PRs to `main`; PRs must keep it green.
|
|
- Update `README.md` / `Docs/*` whenever behaviour or architecture changes.
|