ipeddle 0.1.0__py3-none-any.whl

ipeddle/doctor.py

@@ -0,0 +1,173 @@
+"""``ipeddle doctor``: check the machine and explain what is missing."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import patcher, swiftsdk, toolchain, ui
+from .errors import IpeddleError
+from .fsutil import free_bytes
+from .paths import TRIPLE, Home
+
+GB = 1024 ** 3
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    fix: str = ""
+    required: bool = True
+
+
+def run_checks(home: Home, deep: bool = False) -> list[Check]:
+    checks: list[Check] = []
+    add = checks.append
+
+    add(Check("python", sys.version_info >= (3, 10), platform.python_version(), "ipeddle needs Python 3.10+"))
+    system = platform.system()
+    add(Check("os", system == "Linux", f"{system} {platform.machine()}",
+              "ipeddle targets Linux (on Windows use WSL2; on a Mac just use Xcode)"))
+    add(Check("arch", platform.machine() in ("x86_64", "aarch64", "arm64"), platform.machine(),
+              "Swift for Linux ships for x86_64 and aarch64 only"))
+    for tool, why in (("git", "fetching the SDK from the mirror"), ("tar", "unpacking downloads")):
+        add(Check(tool, shutil.which(tool) is not None, shutil.which(tool) or "not found",
+                  f"install {tool} ({why})", required=tool == "git"))
+
+    free = free_bytes(home.root)
+    st = home.load_state()
+    need = 1 * GB if st.get("complete") else 4 * GB
+    add(Check("disk", free >= need, f"{ui.human_bytes(free)} free at {home.root}",
+              f"free at least {ui.human_bytes(need)} (setup needs ~4 GB: Swift ~2.5 GB, SDK ~0.6 GB)"))
+
+    swift = None
+    if st.get("swift"):
+        try:
+            swift = toolchain.probe(Path(st["swift"]["root"]))
+        except IpeddleError as e:
+            add(Check("swift", False, e.message, "run `ipeddle setup` (or fix the system libraries "
+                      "listed on https://www.swift.org/install/linux/)"))
+    else:
+        swift = toolchain.find_on_path()
+    if swift:
+        ok = toolchain.version_tuple(swift.version) >= toolchain.MIN_SWIFT
+        missing = swift.missing_tools()
+        add(Check("swift", ok and not missing, f"Swift {swift.version} at {swift.root}"
+                  + (f" (missing {', '.join(missing)})" if missing else ""),
+                  "ipeddle needs a swift.org toolchain, 6.1 or newer; `ipeddle setup` downloads one"))
+    elif not any(c.name == "swift" for c in checks):
+        add(Check("swift", False, "not found", "run `ipeddle setup` to download Swift for Linux"))
+
+    linker = st.get("linker", {}).get("path")
+    add(Check("linker", bool(linker) and Path(linker).is_file(), linker or "not set up",
+              "run `ipeddle setup` (downloads an ld64-compatible lld that accepts iOS)"))
+
+    sdk = st.get("sdk", {})
+    derived = Path(sdk["derived"]) if sdk.get("derived") else None
+    if derived and derived.is_dir():
+        rep = patcher.PatchReport.load(derived)
+        learned = sum(len(v) for v in rep.learned.values())
+        add(Check("sdk", True, f"iPhoneOS {sdk.get('version')} (patched: {sum(rep.overlays.values())} "
+                  f"overlay, {sum(rep.merged.values())} merged, {learned} learned symbols)"))
+        src = Path(sdk.get("source", ""))
+        add(Check("sdk source", src.is_dir(), str(src), "the pristine SDK is gone; `ipeddle setup --force`",
+                  required=False))
+    else:
+        add(Check("sdk", False, "not set up", "run `ipeddle setup` (fetches the SDK on this machine)"))
+
+    rt = home.resource_dir / "clang/lib/darwin" / swiftsdk.RT_ARCHIVE
+    add(Check("runtime", rt.exists(), str(rt) if rt.exists() else "not built",
+              "run `ipeddle setup` (builds the availability runtime)"))
+    add(Check("swift sdk bundle", (home.bundle / "swift-sdk.json").exists(), str(home.bundle),
+              "run `ipeddle setup`"))
+
+    try:
+        import PIL  # noqa: F401
+        add(Check("pillow", True, "icons are resized", required=False))
+    except ImportError:
+        add(Check("pillow", False, "not installed: icons are copied unscaled",
+                  "pip install 'ipeddle[icons]'", required=False))
+
+    if deep and all(c.ok for c in checks if c.required) and swift:
+        add(smoke_test(home, swift))
+    return checks
+
+
+SMOKE_SOURCE = """\
+import SwiftUI
+import UIKit
+
+struct SmokeView: View {
+    var body: some View { Text("ipeddle") }
+}
+
+@main
+enum Smoke {
+    static func main() {
+        if #available(iOS 17.0, *) { print(UIDevice.self) }
+        print(SmokeView().body)
+    }
+}
+"""
+
+
+def smoke_test(home: Home, swift, target: str = "16.0", timeout: int = 900) -> Check:
+    """Compile and link a small SwiftUI + UIKit program for arm64-apple-ios.
+
+    Uses the shared module cache, so it also pre-builds the SDK's modules
+    that every app needs (Swift, Foundation, UIKit, SwiftUI ...).
+    """
+    with tempfile.TemporaryDirectory(prefix="ipeddle-smoke-") as tmp:
+        src = Path(tmp) / "smoke.swift"
+        src.write_text(SMOKE_SOURCE)
+        out = Path(tmp) / "smoke"
+        bundle = home.bundle
+        sdk = bundle / "sdk/iPhoneOS.sdk"
+        cmd = [str(swift.tool("swiftc")), "-target", f"{TRIPLE}{target}", "-parse-as-library",
+               "-sdk", str(sdk), "-resource-dir", str(bundle / "resource"),
+               "-I", str(bundle / "resource/shims"),
+               "-use-ld=lld", f"-ld-path={bundle / 'ld64.lld'}",
+               "-Xclang-linker", "-isysroot", "-Xclang-linker", str(sdk),
+               "-Xclang-linker", "-resource-dir", "-Xclang-linker", str(bundle / "resource/clang"),
+               "-runtime-compatibility-version", "none",
+               "-Xfrontend", "-enable-cross-import-overlays",
+               "-Xcc", "-Wno-nullability-completeness",
+               "-Xcc", "-Wno-nullability-inferred-on-nested-type",
+               "-module-cache-path", str(home.module_cache),
+               "-O", str(src), "-o", str(out)]
+        try:
+            p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
+                               env={**os.environ, "TMPDIR": tmp})
+        except subprocess.TimeoutExpired:
+            return Check("test compile", False, f"timed out after {timeout}s", "rerun with IPEDDLE_VERBOSE=1")
+        if p.returncode != 0:
+            errs = [ln.strip() for ln in (p.stdout + p.stderr).splitlines() if "error" in ln][:5]
+            return Check("test compile", False, "; ".join(errs) or "failed",
+                         "run `ipeddle setup --force`; if it persists, the Swift version may not "
+                         "read this SDK's interfaces")
+        return Check("test compile", out.exists(), "compiled and linked a SwiftUI program for iOS")
+
+
+def report(checks: list[Check]) -> bool:
+    ok = True
+    for c in checks:
+        if c.ok:
+            ui.ok(f"{c.name:16} {c.detail}")
+        elif c.required:
+            ok = False
+            ui.fail(f"{c.name:16} {c.detail}")
+            if c.fix:
+                ui.info(f"{'':16} -> {c.fix}")
+        else:
+            ui.warn(f"{c.name:16} {c.detail}")
+            if c.fix:
+                ui.info(f"{'':16} -> {c.fix}")
+    return ok

ipeddle/errors.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+class IpeddleError(Exception):
+    """An error with a human explanation and, ideally, a fix."""
+
+    def __init__(self, message: str, hint: str | None = None, code: int = 1):
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+        self.code = code

ipeddle/fsutil.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import contextlib
+import errno
+import fcntl
+import os
+import shutil
+from pathlib import Path
+
+
+@contextlib.contextmanager
+def private_tmp(path: Path):
+    """Point TMPDIR at ``path`` for child processes (SwiftPM and the Swift
+    driver leave empty ``TemporaryDirectory.*`` folders behind) and delete it."""
+    old = os.environ.get("TMPDIR")
+    path.mkdir(parents=True, exist_ok=True)
+    os.environ["TMPDIR"] = str(path)
+    try:
+        yield path
+    finally:
+        if old is None:
+            os.environ.pop("TMPDIR", None)
+        else:
+            os.environ["TMPDIR"] = old
+        rmtree(path)
+
+
+@contextlib.contextmanager
+def locked(path: Path):
+    """An exclusive advisory lock (serialises setup and SDK patching)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a+") as fh:
+        fcntl.flock(fh, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(fh, fcntl.LOCK_UN)
+
+
+def tree_size(path: Path) -> int:
+    """Bytes used by ``path`` (each hard-linked inode counted once)."""
+    seen = set()
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            try:
+                st = os.lstat(os.path.join(root, f))
+            except OSError:
+                continue
+            key = (st.st_dev, st.st_ino)
+            if key in seen:
+                continue
+            seen.add(key)
+            total += st.st_blocks * 512
+    return total
+
+
+def own_and_shared(path: Path) -> tuple[int, int]:
+    """(bytes only reachable from ``path``, bytes hard-linked from elsewhere).
+
+    Files whose link count exceeds the links found under ``path`` are
+    shared with another tree (e.g. the pristine SDK) and cost no extra space.
+    """
+    counts: dict[tuple[int, int], list] = {}
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            try:
+                st = os.lstat(os.path.join(root, f))
+            except OSError:
+                continue
+            key = (st.st_dev, st.st_ino)
+            entry = counts.setdefault(key, [0, st.st_nlink, st.st_blocks * 512])
+            entry[0] += 1
+    own = shared = 0
+    for seen, nlink, size in counts.values():
+        if nlink > seen:
+            shared += size
+        else:
+            own += size
+    return own, shared
+
+
+def link_tree(src: Path, dst: Path) -> tuple[int, int]:
+    """Mirror ``src`` into ``dst`` using hard links (copy when not possible).
+
+    Returns ``(linked, copied)``.  Files are later patched with
+    ``os.replace`` so the source tree is never modified.
+    """
+    linked = copied = 0
+    can_link = True
+    for root, dirs, files in os.walk(src):
+        rel = os.path.relpath(root, src)
+        out = dst / rel if rel != "." else dst
+        out.mkdir(parents=True, exist_ok=True)
+        for d in list(dirs):
+            sp = os.path.join(root, d)
+            if os.path.islink(sp):
+                os.symlink(os.readlink(sp), out / d)
+                dirs.remove(d)
+        for f in files:
+            sp = os.path.join(root, f)
+            dp = out / f
+            if os.path.islink(sp):
+                os.symlink(os.readlink(sp), dp)
+                continue
+            if can_link:
+                try:
+                    os.link(sp, dp)
+                    linked += 1
+                    continue
+                except OSError as e:
+                    if e.errno not in (errno.EXDEV, errno.EPERM, errno.EMLINK, errno.ENOTSUP):
+                        raise
+                    can_link = False
+            shutil.copy2(sp, dp)
+            copied += 1
+    return linked, copied
+
+
+def rmtree(path: Path) -> None:
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+    elif path.exists():
+        shutil.rmtree(path)
+
+
+def free_bytes(path: Path) -> int:
+    p = Path(path)
+    while not p.exists() and p != p.parent:
+        p = p.parent
+    return shutil.disk_usage(p).free

ipeddle/inspect.py

@@ -0,0 +1,329 @@
+"""``ipeddle inspect``: sanity checks for an .ipa (or a .app directory)."""
+
+from __future__ import annotations
+
+import plistlib
+import posixpath
+import re
+import struct
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import macho, tbd
+from .config import _BUNDLE_ID_RE
+from .errors import IpeddleError
+from .patcher import tbd_path
+
+REQUIRED_KEYS = ("CFBundleExecutable", "CFBundleIdentifier", "CFBundleShortVersionString",
+                 "CFBundleVersion", "CFBundlePackageType", "MinimumOSVersion")
+
+
+@dataclass
+class Finding:
+    level: str  # "error" | "warning" | "info"
+    message: str
+
+
+@dataclass
+class Report:
+    app_name: str = ""
+    bundle_id: str = ""
+    executable: str = ""
+    archs: list[str] = field(default_factory=list)
+    platform: str | None = None
+    min_os: str | None = None
+    sdk: str | None = None
+    size: int = 0
+    dylibs: list[str] = field(default_factory=list)
+    frameworks: list[str] = field(default_factory=list)
+    bundles: list[str] = field(default_factory=list)
+    imports: int = 0
+    unresolved: list[tuple[str, str]] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+
+    def add(self, level: str, msg: str) -> None:
+        self.findings.append(Finding(level, msg))
+
+    @property
+    def ok(self) -> bool:
+        return not any(f.level == "error" for f in self.findings)
+
+    def to_json(self) -> dict:
+        return {
+            "app": self.app_name, "bundle_id": self.bundle_id, "executable": self.executable,
+            "archs": self.archs, "platform": self.platform, "min_os": self.min_os, "sdk": self.sdk,
+            "size": self.size, "dylibs": self.dylibs, "frameworks": self.frameworks,
+            "bundles": self.bundles, "imports": self.imports,
+            "unresolved": [{"library": lib, "symbol": s} for lib, s in self.unresolved],
+            "findings": [f.__dict__ for f in self.findings], "ok": self.ok,
+        }
+
+
+class _Files:
+    """Uniform read access to an .ipa (zip) or an .app directory."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self.zip = None
+        if path.is_dir():
+            self.names = [str(p.relative_to(path.parent)) for p in path.rglob("*") if p.is_file()]
+            self.root = path.parent
+        else:
+            try:
+                self.zip = zipfile.ZipFile(path)
+            except zipfile.BadZipFile as e:
+                raise IpeddleError(f"{path} is not a valid .ipa (zip) file") from e
+            self.names = [n for n in self.zip.namelist() if not n.endswith("/")]
+
+    def read(self, name: str) -> bytes:
+        if self.zip:
+            return self.zip.read(name)
+        return (self.root / name).read_bytes()
+
+    def size(self) -> int:
+        if self.zip:
+            return sum(i.file_size for i in self.zip.infolist())
+        return sum((self.root / n).stat().st_size for n in self.names)
+
+
+class SymbolIndex:
+    """Exports of SDK libraries, following re-exports."""
+
+    def __init__(self, sdk: Path):
+        self.sdk = sdk
+        self._docs: dict[str, tbd.TbdDocument | None] = {}
+        self._closure: dict[str, set[str]] = {}
+
+    def doc(self, install_name: str) -> tbd.TbdDocument | None:
+        if install_name not in self._docs:
+            p = tbd_path(self.sdk, install_name)
+            found = None
+            if p is not None:
+                for d in tbd.read(p):
+                    self._docs.setdefault(d.install_name, d)
+                    if d.install_name == install_name:
+                        found = d
+            self._docs[install_name] = found
+        return self._docs[install_name]
+
+    def exports(self, install_name: str, _depth: int = 0) -> set[str] | None:
+        if install_name in self._closure:
+            return self._closure[install_name]
+        d = self.doc(install_name)
+        if d is None:
+            return None
+        out = set(d.exports)
+        self._closure[install_name] = out  # break cycles
+        if _depth < 8:
+            for r in d.reexports:
+                sub = self.exports(r, _depth + 1)
+                if sub:
+                    out |= sub
+        return out
+
+    def reexporters(self, install_name: str, linked: list[str]) -> list[str]:
+        out = []
+        for lib in linked:
+            d = self.doc(lib)
+            if d and install_name in d.reexports:
+                out.append(lib)
+        return out
+
+
+def _find_app(names: list[str]) -> str:
+    apps = sorted({m.group(1) for n in names if (m := re.match(r"^(Payload/[^/]+\.app)/", n))})
+    if not apps:
+        apps = sorted({m.group(1) for n in names if (m := re.match(r"^([^/]+\.app)/", n))})
+    if not apps:
+        raise IpeddleError("no Payload/<Name>.app inside; this is not an iOS app archive")
+    return apps[0]
+
+
+def _ver_tuple(v: str | None) -> tuple[int, ...]:
+    return tuple(int(x) for x in re.findall(r"\d+", v or "")[:3])
+
+
+def inspect(path: Path, sdk: Path | None = None) -> Report:
+    path = Path(path)
+    if not path.exists():
+        raise IpeddleError(f"{path} not found")
+    files = _Files(path)
+    rep = Report(size=files.size())
+    app = _find_app(files.names)
+    rep.app_name = posixpath.basename(app)
+
+    try:
+        info = plistlib.loads(files.read(f"{app}/Info.plist"))
+    except KeyError:
+        rep.add("error", "Info.plist is missing")
+        return rep
+    except Exception as e:
+        rep.add("error", f"Info.plist cannot be parsed: {e}")
+        return rep
+
+    for k in REQUIRED_KEYS:
+        if k not in info:
+            rep.add("error", f"Info.plist lacks {k}")
+    rep.bundle_id = str(info.get("CFBundleIdentifier", ""))
+    if rep.bundle_id and not _BUNDLE_ID_RE.match(rep.bundle_id):
+        rep.add("error", f"CFBundleIdentifier {rep.bundle_id!r} is not a valid bundle id")
+    if info.get("CFBundlePackageType", "APPL") != "APPL":
+        rep.add("error", "CFBundlePackageType is not APPL")
+    if "UILaunchScreen" not in info and "UILaunchStoryboardName" not in info:
+        rep.add("warning", "no UILaunchScreen: the app will run letterboxed on modern iPhones")
+    if info.get("UILaunchStoryboardName") and not any(
+            n.startswith(f"{app}/{info['UILaunchStoryboardName']}.storyboardc") for n in files.names):
+        rep.add("error", "UILaunchStoryboardName points to a storyboard that is not in the app")
+    if info.get("UIMainStoryboardFile") and not any(
+            n.startswith(f"{app}/{info['UIMainStoryboardFile']}.storyboardc") for n in files.names):
+        rep.add("error", "UIMainStoryboardFile points to a storyboard that is not in the app")
+    for icon in info.get("CFBundleIcons", {}).get("CFBundlePrimaryIcon", {}).get("CFBundleIconFiles", []):
+        if not any(n.startswith(f"{app}/{icon}") for n in files.names):
+            rep.add("warning", f"icon {icon} is listed in Info.plist but not bundled")
+    if not info.get("CFBundleIcons") and not any(n.endswith("Assets.car") for n in files.names):
+        rep.add("warning", "no app icon")
+    if any(n.endswith(".storyboard") or n.endswith(".xib") for n in files.names):
+        rep.add("error", "uncompiled .storyboard/.xib files in the bundle")
+    if any(posixpath.splitext(n)[1] == ".xcassets" or ".xcassets/" in n for n in files.names):
+        rep.add("warning", "an uncompiled asset catalog (.xcassets) is in the bundle")
+
+    exe_name = str(info.get("CFBundleExecutable", ""))
+    rep.executable = exe_name
+    exe_path = f"{app}/{exe_name}"
+    if exe_path not in files.names:
+        rep.add("error", f"CFBundleExecutable {exe_name!r} is not in the bundle")
+        return rep
+    data = files.read(exe_path)
+    if not macho.is_macho(data):
+        rep.add("error", f"{exe_name} is not a Mach-O binary")
+        return rep
+    try:
+        slices = macho.parse(data)
+    except (macho.MachOError, IndexError, ValueError, struct.error) as e:
+        rep.add("error", f"cannot parse {exe_name}: {e}")
+        return rep
+    rep.archs = [s.arch for s in slices]
+    main = next((s for s in slices if s.arch == "arm64"), None)
+    if main is None:
+        rep.add("error", "no arm64 slice (iOS devices need arm64)")
+        main = slices[0]
+    rep.platform, rep.min_os, rep.sdk = main.platform, main.minos, main.sdk
+    if main.platform != "iOS":
+        rep.add("error", f"built for {main.platform or 'an unknown platform'}, not iOS devices")
+    plist_min = str(info.get("MinimumOSVersion", ""))
+    if plist_min and main.minos and _ver_tuple(plist_min) != _ver_tuple(main.minos):
+        rep.add("warning", f"Info.plist MinimumOSVersion {plist_min} != binary minimum {main.minos}")
+    if main.encrypted:
+        rep.add("error", "the binary is FairPlay-encrypted (cryptid=1); it cannot be re-signed")
+    if not main.has_main:
+        rep.add("error", "the executable has no entry point (LC_MAIN)")
+    if main.signed:
+        rep.add("info", "the binary carries a code signature (ipeddle builds are unsigned; "
+                        "sideloading tools re-sign anyway)")
+    rep.dylibs = [d.path + (" (weak)" if d.kind == "weak" else "") for d in main.dylibs]
+    rep.imports = len(main.imports)
+
+    rep.frameworks = sorted({m.group(1) for n in files.names
+                             if (m := re.match(rf"^{re.escape(app)}/Frameworks/([^/]+)", n))})
+    rep.bundles = sorted({m.group(1) for n in files.names
+                          if (m := re.match(rf"^{re.escape(app)}/([^/]+\.bundle)/", n))})
+
+    # Embedded libraries referenced through @rpath must be in Frameworks/.
+    for d in main.dylibs:
+        if d.path.startswith("@rpath/") or d.path.startswith("@executable_path/"):
+            rel = d.path.split("/", 1)[1]
+            if not any(n == f"{app}/Frameworks/{rel}" or n.endswith("/" + rel) for n in files.names):
+                lvl = "warning" if d.kind == "weak" else "error"
+                rep.add(lvl, f"{d.path} is linked but not embedded in Frameworks/")
+    for fw in rep.frameworks:
+        base = f"{app}/Frameworks/{fw}"
+        binpath = f"{base}/{fw[:-len('.framework')]}" if fw.endswith(".framework") else base
+        if binpath not in files.names:
+            continue
+        try:
+            fsl = macho.parse(files.read(binpath))
+        except (macho.MachOError, IndexError, ValueError, struct.error):
+            rep.add("error", f"Frameworks/{fw}: not a valid Mach-O")
+            continue
+        if not any(s.arch == "arm64" and s.platform == "iOS" for s in fsl):
+            rep.add("error", f"Frameworks/{fw}: no arm64 iOS-device slice "
+                             f"({', '.join(f'{s.arch}/{s.platform}' for s in fsl)})")
+        elif any(_ver_tuple(s.minos) > _ver_tuple(main.minos) for s in fsl if s.arch == "arm64"):
+            rep.add("warning", f"Frameworks/{fw} requires a newer iOS than the app ({main.minos})")
+    if rep.frameworks and "@executable_path/Frameworks" not in main.rpaths:
+        rep.add("error", "embedded frameworks present but no @executable_path/Frameworks rpath")
+
+    flat = [i.name for i in main.imports if i.ordinal == macho.BIND_SPECIAL_FLAT]
+    if flat:
+        rep.add("warning", f"{len(flat)} symbol(s) use flat-namespace lookup (resolved only at launch)")
+
+    if sdk is not None:
+        _check_symbols(rep, main, sdk)
+    else:
+        rep.add("info", "symbol check skipped (no SDK: run `ipeddle setup` or pass --sdk)")
+    return rep
+
+
+def _check_symbols(rep: Report, sl: macho.Slice, sdk: Path) -> None:
+    idx = SymbolIndex(sdk)
+    linked = [d.path for d in sl.dylibs]
+    unknown_libs = set()
+    for imp in sl.imports:
+        if imp.ordinal <= 0:
+            continue
+        lib = sl.library_for(imp)
+        if lib.startswith("@") or lib.startswith("<"):
+            continue
+        ex = idx.exports(lib)
+        if ex is None:
+            unknown_libs.add(lib)
+            continue
+        if imp.name not in ex and not imp.weak:
+            rep.unresolved.append((lib, imp.name))
+    for lib in sorted(unknown_libs):
+        rep.add("warning", f"{lib}: no stub in the SDK, its symbols were not checked")
+    if rep.unresolved:
+        rep.add("error", f"{len(rep.unresolved)} imported symbol(s) are not exported by the library "
+                         "they are bound to (the app would crash at launch)")
+    # A library linked directly that the SDK says is re-exported by another
+    # linked one is usually a split-out framework (e.g. iOS 18's
+    # SwiftUICore): on older iOS it may not exist.
+    for d in sl.dylibs:
+        if d.kind == "weak":
+            continue
+        parents = idx.reexporters(d.path, [x for x in linked if x != d.path])
+        parents = [p for p in parents if p.startswith("/System/Library/Frameworks/")]
+        if parents and d.path.startswith("/System/Library/Frameworks/"):
+            rep.add("warning", f"{posixpath.basename(d.path)} is linked directly but is re-exported by "
+                               f"{', '.join(posixpath.basename(p) for p in parents)}; it may not exist "
+                               f"on iOS {rep.min_os}")
+
+
+def format_report(rep: Report, verbose: bool = False) -> str:
+    from .ui import human_bytes
+
+    lines = [
+        f"App:        {rep.app_name}  ({rep.bundle_id or '?'})",
+        f"Executable: {rep.executable}  [{', '.join(rep.archs) or '?'}]",
+        f"Platform:   {rep.platform or '?'}  min {rep.min_os or '?'}  (built with SDK {rep.sdk or '?'})",
+        f"Size:       {human_bytes(rep.size)} uncompressed",
+        f"Links:      {len(rep.dylibs)} libraries, {rep.imports} imported symbols",
+    ]
+    if rep.frameworks:
+        lines.append(f"Embedded:   {', '.join(rep.frameworks)}")
+    if rep.bundles:
+        lines.append(f"Bundles:    {', '.join(rep.bundles)}")
+    if verbose:
+        lines.append("Libraries:")
+        lines.extend(f"  {d}" for d in rep.dylibs)
+    if rep.unresolved:
+        lines.append("Unresolved symbols:")
+        for lib, s in rep.unresolved[: (None if verbose else 20)]:
+            lines.append(f"  {s}  <- {lib}")
+        if not verbose and len(rep.unresolved) > 20:
+            lines.append(f"  ... {len(rep.unresolved) - 20} more (use --verbose)")
+    for f in rep.findings:
+        lines.append(f"{f.level.upper():8}{f.message}")
+    lines.append("Result:     " + ("OK" if rep.ok else "PROBLEMS FOUND"))
+    return "\n".join(lines)