Native mobile

#!/usr/bin/env python3
"""Android mirrors iOS name for name: every screen, design-system component, data role and token on one
side has its counterpart on the other.

    python3 tooling/check_mirror.py [--root DIR]

Under `--root`, Swift files are the iOS app and Kotlin files the Android app (tests and build output
are not read). It compares top-level, non-private declarations:

- a SwiftUI `XView` in a `Features` folder and a Compose `XScreen` in a `features` folder;
- every type in `DesignSystem/Components` and every declaration in `designsystem/components`;
- every `…Repository`, `…RemoteSource` and `…LocalStore`;
- the members of `AppSpacing`, `AppTypography` and `AppColors`.

A difference that exists only because the toolkits differ is listed in a `platform-only.json` file
anywhere under the root, `{"Name": "why it exists on one platform only"}`; a name listed without a
reason is refused. A project with only one platform has nothing to mirror and passes.
"""

import argparse
import json
import re
import sys
from pathlib import Path

SKIP = {"build", ".build", ".gradle", ".git", ".swiftpm", "DerivedData", "Pods", "node_modules", "tooling", "test",
        "androidTest", "testing", "Tests"}
DECLARATION = re.compile(
    r"^(?:@\w+(?:\([^)]*\))?\s+)*(?:(?:public|internal|final|open|data|enum|sealed|abstract|inline|value|"
    r"indirect|nonisolated)\s+)*(struct|class|enum|protocol|actor|interface|object|fun)\s+(\w+)\b(?!\.)")
PRIVATE = re.compile(r"^(?:@\w+(?:\([^)]*\))?\s+)*(private|fileprivate)\b")
ROLES = ("Repository", "RemoteSource", "LocalStore")
TOKENS = ("AppSpacing", "AppTypography", "AppColors")


def sources(root, suffix):
    for path in sorted(root.rglob(f"*{suffix}")):
        parts = path.relative_to(root).parts[:-1]
        if not any(p in SKIP or p.endswith("Tests") for p in parts) and path.name != "Package.swift":
            yield path


def declarations(path):
    """Top-level, non-private names declared in a file (an indented declaration is nested)."""
    names = set()
    for line in path.read_text(encoding="utf-8").splitlines():
        if PRIVATE.match(line):
            continue
        match = DECLARATION.match(line)
        if match:
            names.add(match.group(2))
    return names


def members(path):
    text = path.read_text(encoding="utf-8")
    return set(re.findall(r"^\s+(?:static\s+(?:let|var)|(?:const\s+)?val)\s+(\w+)", text, re.MULTILINE))


def side(root, suffix, features, components):
    out = {"screens": set(), "components": set(), "roles": set(), "tokens": {}}
    for path in sources(root, suffix):
        parts = path.relative_to(root).parts[:-1]
        names = declarations(path)
        if features in parts:
            out["screens"] |= {n for n in names if n.endswith("View" if suffix == ".swift" else "Screen")}
        if f"/{components}/" in f"/{'/'.join(parts)}/":
            out["components"] |= names
        out["roles"] |= {n for n in names if n.endswith(ROLES)}
        if path.stem in TOKENS:
            out["tokens"].setdefault(path.stem, set()).update(members(path))
    return out


def platform_only(root):
    allowed, problems = {}, []
    for path in sources(root, "platform-only.json"):
        for name, reason in json.loads(path.read_text(encoding="utf-8")).items():
            if not str(reason).strip():
                problems.append(f"{path.relative_to(root)}: {name} is listed without a reason")
            allowed[name] = reason
    return allowed, problems


def violations(root):
    root = Path(root).resolve()
    ios = side(root, ".swift", "Features", "DesignSystem/Components")
    android = side(root, ".kt", "features", "designsystem/components")
    if not any(ios.values()) or not any(android.values()):
        return []
    allowed, out = platform_only(root)

    def compare(what, mine, theirs, other):
        for name in sorted(mine - theirs - set(allowed)):
            out.append(f"{what}: {name} has no {other} counterpart")

    screens_ios = {n[: -len("View")] for n in ios["screens"]}
    screens_android = {n[: -len("Screen")] for n in android["screens"]}
    compare("screen", {f"{n}View" for n in screens_ios - screens_android}, set(), "Android (…Screen)")
    compare("screen", {f"{n}Screen" for n in screens_android - screens_ios}, set(), "iOS (…View)")
    compare("component", ios["components"], android["components"], "Android")
    compare("component", android["components"], ios["components"], "iOS")
    compare("role", ios["roles"], android["roles"], "Android")
    compare("role", android["roles"], ios["roles"], "iOS")
    for token in TOKENS:
        mine, theirs = ios["tokens"].get(token, set()), android["tokens"].get(token, set())
        compare(f"token {token}", {f"{token}.{m}" for m in mine - theirs}, set(), "Android")
        compare(f"token {token}", {f"{token}.{m}" for m in theirs - mine}, set(), "iOS")
    return out


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--root", default=".", help="the folder holding both apps (default: here)")
    args = parser.parse_args(argv)
    found = violations(args.root)
    for line in found:
        print(line)
    if found:
        print(f"❌ {len(found)} difference(s) between the iOS and Android apps")
        return 1
    print("✅ Android mirrors iOS")
    return 0


if __name__ == "__main__":
    sys.exit(main())

{
  "AppNavigationStack": "SwiftUI's stack is a design-system wrapper; Compose navigates with the NavHost the shell owns",
  "AppTextRole": "Kotlin cannot nest a type in a composable function; iOS nests it as AppText.Role"
}

App/
├── MainApp                # composition root, built in tiers
├── Navigation/            # root switch, shell, blocking covers
├── Core/                  # Auth, Network, Config, Data, Outbox, Telemetry, Push
├── DesignSystem/          # Tokens, Components, Forms, Icons, Guards
└── Features/<Product>/    # one vertical slice per product

import Foundation
import Observation

/// Every kind of thing the app can open. A new case does not compile until `FeatureRouter` maps it.
enum FeatureKind: String, Sendable {
    case project
}

/// A reference to one thing, from a link, a notification or another feature.
struct EntityRef: Equatable, Sendable {
    let kind: FeatureKind
    let id: String
}

/// Where the shell navigates. Typed: no string routes.
enum Route: Hashable, Sendable {
    case projects
    case project(id: String)
}

/// The one map from a reference to its screen.
enum FeatureRouter {
    static func route(for ref: EntityRef) -> Route {
        switch ref.kind {
        case .project: .project(id: ref.id)
        }
    }

    /// `<scheme>://<kind>/<id>`, or a universal link's `/<kind>/<id>` path.
    static func ref(from url: URL) -> EntityRef? {
        let path = url.pathComponents.filter { $0 != "/" }
        let parts = url.scheme == "https" ? path : [url.host()].compactMap { $0 } + path
        guard parts.count == 2, let kind = FeatureKind(rawValue: parts[0]) else { return nil }
        return EntityRef(kind: kind, id: parts[1])
    }
}

/// Every way in writes here: a notification tap, a universal link, a sign-in callback. The shell takes it
/// on cold start and while running, resets to the root and pushes the destination, so Back lands on Home.
@Observable @MainActor
final class PendingDeepLinkStore {
    private(set) var pending: Route?

    func open(_ url: URL) {
        guard let ref = FeatureRouter.ref(from: url) else { return }
        pending = FeatureRouter.route(for: ref)
    }

    /// The shell took the destination.
    func take() -> Route? {
        defer { pending = nil }
        return pending
    }
}

import Foundation
import Synchronization

/// The one outbound rule. Every send asks it to admit the request, then settles the answer with it:
///
/// - a request to the platform's origin names the API version and the build; any other request, and
///   any redirect away, carries neither, whoever set them;
/// - after a must-update answer, requests to the platform stay on the phone, except the startup reads
///   and one probe at a time, until an answer names its version again.
///
/// `scripts`' guard refuses `URLSession` anywhere but `Core/Network`, so no request goes around it.
final class RequestPolicy: Sendable {
    static let versionHeader = "API-Version"
    static let buildHeader = "App-Version"

    /// What a send carries from `admitted` to `settle`.
    struct Admission: Sendable {
        let request: URLRequest
        /// This request is the one probe let through while the build is refused.
        let isProbe: Bool
    }

    private struct State {
        var refused: Bool
        var probing = false
    }

    private let config: AppConfig
    private let memory: UpdateRefusalMemory
    private let startupPaths: Set<String>
    private let state: Mutex<State>
    private let onChange: @Sendable (Bool) -> Void

    /// `onChange` hears every change of standing, so the must-update cover opens and closes while the
    /// app runs, not only at launch.
    init(config: AppConfig, memory: UpdateRefusalMemory, startupPaths: Set<String> = ["/api/startup"],
         onChange: @escaping @Sendable (Bool) -> Void = { _ in }) {
        self.config = config
        self.memory = memory
        self.startupPaths = startupPaths
        self.onChange = onChange
        state = Mutex(State(refused: memory.isRefused(build: config.appVersion)))
    }

    var isRefused: Bool { state.withLock { $0.refused } }

    /// Whether `url` is on the platform's origin: same scheme, host and port.
    func isPlatform(_ url: URL?) -> Bool {
        guard let url else { return false }
        return url.scheme == config.apiBaseURL.scheme && url.host() == config.apiBaseURL.host()
            && url.port == config.apiBaseURL.port
    }

    /// `request` as it may leave. Also applied to a redirect's new request, so a hop away from the
    /// platform carries neither header.
    func prepared(_ request: URLRequest) -> URLRequest {
        var request = request
        request.setValue(nil, forHTTPHeaderField: Self.versionHeader)
        request.setValue(nil, forHTTPHeaderField: Self.buildHeader)
        guard isPlatform(request.url) else { return request }
        request.setValue(config.apiVersion, forHTTPHeaderField: Self.versionHeader)
        request.setValue(config.appVersion, forHTTPHeaderField: Self.buildHeader)
        return request
    }

    /// `request` as it may leave, or nil when it must stay on the phone. A caller answers nil as the
    /// must-update error without sending anything.
    func admitted(_ request: URLRequest) -> Admission? {
        let request = prepared(request)
        guard isPlatform(request.url), !startupPaths.contains(request.url?.path() ?? "") else {
            return Admission(request: request, isProbe: false)
        }
        return state.withLock { state in
            guard state.refused else { return Admission(request: request, isProbe: false) }
            guard !state.probing else { return nil }
            state.probing = true
            return Admission(request: request, isProbe: true)
        }
    }

    /// Tells the rule what the answer to an admitted request said, or that none came (`response` nil).
    /// Only an answer from the platform counts: must-update refuses this build, any other answer naming
    /// its version lifts the refusal.
    func settle(_ admission: Admission, response: HTTPURLResponse?, body: Data) {
        let verdict = response.flatMap { response -> Bool? in
            guard isPlatform(response.url) else { return nil }
            if AppError.of(status: response.statusCode, body: body) == .updateRequired { return true }
            return response.value(forHTTPHeaderField: Self.versionHeader) != nil ? false : nil
        }
        let changed = state.withLock { state in
            if admission.isProbe { state.probing = false }
            guard let refused = verdict, refused != state.refused else { return false }
            state.refused = refused
            return true
        }
        guard changed, let refused = verdict else { return }
        memory.remember(refused: refused, build: config.appVersion)
        onChange(refused)
    }
}

/// Where a must-update refusal is kept, so the cover opens at every launch of a refused build.
protocol UpdateRefusalMemory: Sendable {
    func isRefused(build: String) -> Bool
    func remember(refused: Bool, build: String)
}

struct DefaultsUpdateRefusalMemory: UpdateRefusalMemory {
    let key = "network.refusedBuild"

    func isRefused(build: String) -> Bool { UserDefaults.standard.string(forKey: key) == build }

    func remember(refused: Bool, build: String) {
        UserDefaults.standard.set(refused ? build : nil, forKey: key)
    }
}

import Foundation

/// Answers a send with the bearer token to carry, and renews it once when the server refused it.
protocol CredentialProviding: Sendable {
    func bearer() async throws -> String
    func renew() async throws
}

/// The one way a request reaches the platform: admitted by the request rule, carrying credentials
/// unless it is a public read, retried by one owner, and turned into an `AppError` on failure.
final class APIClient: Sendable {
    /// How many times a repeatable request is tried in all.
    static let attempts = 3

    private let policy: RequestPolicy
    private let transport: HTTPTransport
    private let credentials: CredentialProviding
    private let pause: @Sendable (Int) async -> Void

    init(policy: RequestPolicy, transport: HTTPTransport, credentials: CredentialProviding,
         pause: @escaping @Sendable (Int) async -> Void = { attempt in
             try? await Task.sleep(for: .milliseconds(250 << attempt))
         }) {
        self.policy = policy
        self.transport = transport
        self.credentials = credentials
        self.pause = pause
    }

    /// The body of a successful answer.
    ///
    /// - `publicRead`: no credentials and no cookies, so a cache in front may share the answer.
    /// - A `401` renews the credentials once and sends again; a second `401` is `unauthorized`.
    /// - Only a read, or a request carrying an `Idempotency-Key`, is repeated after a retryable failure.
    func send(_ request: URLRequest, publicRead: Bool = false) async throws -> Data {
        let repeatable = request.httpMethod ?? "GET" == "GET" || request.value(forHTTPHeaderField: "Idempotency-Key") != nil
        var renewed = false
        var attempt = 0
        while true {
            do {
                return try await sendOnce(request, publicRead: publicRead)
            } catch AppError.unauthorized where !publicRead && !renewed {
                renewed = true
                try await credentials.renew()
            } catch let error as AppError where error.isRetryable && repeatable && attempt + 1 < Self.attempts {
                await pause(attempt)
                attempt += 1
            }
        }
    }

    private func sendOnce(_ request: URLRequest, publicRead: Bool) async throws -> Data {
        var request = request
        if !publicRead {
            request.setValue("Bearer \(try await credentials.bearer())", forHTTPHeaderField: "Authorization")
        }
        guard let admission = policy.admitted(request) else { throw AppError.updateRequired }
        let data: Data
        let response: HTTPURLResponse
        do {
            (data, response) = try await transport.send(admission.request)
        } catch {
            policy.settle(admission, response: nil, body: Data())
            throw (error as? AppError) ?? .offline
        }
        policy.settle(admission, response: response, body: data)
        if let error = AppError.of(status: response.statusCode, body: data) { throw error }
        return data
    }
}

import Foundation
import Observation

/// An action the person took, kept on the phone until the platform takes it. Its id is the
/// idempotency key the platform deduplicates on, so sending it twice is harmless.
struct KeptAction: Codable, Equatable, Sendable {
    let id: String
    let kind: String
    let subjectID: String
}

/// Sends one kept action, carrying its id as `Idempotency-Key`. Throws when the platform did not take it.
@MainActor
protocol KeptActionSending: AnyObject {
    func send(_ action: KeptAction) async throws
}

/// Where waiting actions are saved, so they survive a relaunch.
protocol KeptActionStoring {
    func load() -> [KeptAction]
    func save(_ actions: [KeptAction])
}

/// Actions are saved before they are sent and shown as done at once. The outbox sends what waits when an
/// action is added, at launch, back in the foreground and back online. An action leaves only when the
/// platform took it or refused it for good; a refusal is shown once. A must-update answer pauses the
/// outbox: nothing is dropped.
@Observable @MainActor
final class ActionOutbox {
    private(set) var waiting: [KeptAction]
    /// The last action the platform refused for good, for the root to show once.
    private(set) var refused: KeptAction?
    private(set) var isPaused = false

    @ObservationIgnored private let store: KeptActionStoring
    @ObservationIgnored private let sender: KeptActionSending

    init(store: KeptActionStoring, sender: KeptActionSending) {
        self.store = store
        self.sender = sender
        waiting = store.load()
    }

    func add(_ action: KeptAction) async {
        waiting.append(action)
        store.save(waiting)
        await flush()
    }

    /// Sends every waiting action once, in order; stops at the first that may succeed later.
    func flush() async {
        isPaused = false
        while let action = waiting.first {
            do {
                try await sender.send(action)
            } catch AppError.updateRequired {
                isPaused = true
                return
            } catch let error as AppError where !error.isRetryable && error != .unauthorized {
                refused = action
            } catch {
                return
            }
            waiting.removeFirst()
            store.save(waiting)
        }
    }

    func noticeShown() { refused = nil }
}

struct DefaultsKeptActionStore: KeptActionStoring {
    let key: String

    func load() -> [KeptAction] {
        UserDefaults.standard.data(forKey: key).flatMap { try? JSONDecoder().decode([KeptAction].self, from: $0) } ?? []
    }

    func save(_ actions: [KeptAction]) {
        UserDefaults.standard.set(try? JSONEncoder().encode(actions), forKey: key)
    }
}

# The handbook's mobile example: one feature built twice, iOS leading and Android mirroring it name for
# name, each checked the way the pages say.
.DEFAULT_GOAL := check
.PHONY: check ios android

check: ios android ## both apps, each with its tests and its rules

ios: ## SwiftUI: swift test, then the SwiftUI rules
	$(MAKE) -C ios check

android: ## Jetpack Compose: the JVM tests and screenshot tests, then the Compose rules and the mirror rule
	$(MAKE) -C android check