tools: ui-lab renders view code in seconds; wire-app-sources.py

scripts/lint-pbxproj-test-wiring.sh

@@ -278,9 +278,14 @@ if [ "$TARGET_NAME" = "cmuxTests" ] && [ "$TESTS_REL" = "cmuxTests" ]; then
   echo "Run ./scripts/sync-test-wiring to reconcile direct $TESTS_REL/*.swift files."
   echo "Use ./scripts/sync-test-wiring --check for a read-only authoring/CI check."
 else
-  # sync-test-wiring only reconciles cmuxTests. Other targets are wired by hand.
-  echo "sync-test-wiring only reconciles cmuxTests; add the four $TARGET_NAME"
-  echo "entries above by hand (or in Xcode) for $TESTS_REL/*.swift."
+  # sync-test-wiring only reconciles cmuxTests.
+  if [ "$TARGET_NAME" = "cmux" ] && [ "$TESTS_REL" = "Sources" ]; then
+    echo "Run ./scripts/wire-app-sources.py to add the four entries for each"
+    echo "unwired Sources/**/*.swift file (next to a wired sibling)."
+  else
+    echo "sync-test-wiring only reconciles cmuxTests; add the four $TARGET_NAME"
+    echo "entries above by hand (or in Xcode) for $TESTS_REL/*.swift."
+  fi
 fi
 echo "This lint remains the defensive $TARGET_NAME Sources-phase guard."
 exit 1

scripts/ui-lab/UILab.swift

@@ -0,0 +1,104 @@
+import AppKit
+import SwiftUI
+
+/// Rendering support for ui-lab harnesses (see scripts/ui-lab/ui-lab.py).
+/// A harness calls `UILab.main { ... }` and, inside it,
+/// `UILab.render(name:) { scheme in ... }` to build and render its view.
+/// The output directory is the process's first argument.
+enum UILab {
+    static let outputDirectory: URL = {
+        let path = CommandLine.arguments.dropFirst().first ?? FileManager.default.currentDirectoryPath
+        return URL(fileURLWithPath: path, isDirectory: true)
+    }()
+
+    /// A harness's entry point: sets up AppKit (an application, so
+    /// appearances and system colors resolve) and runs `body` on the main actor.
+    static func main(_ body: @MainActor () -> Void) {
+        MainActor.assumeIsolated {
+            _ = NSApplication.shared
+            NSApp.setActivationPolicy(.prohibited)
+            body()
+        }
+    }
+
+    /// Writes `<name>-light@2x.png` and `<name>-dark@2x.png`, and, when
+    /// `detail` is set, `<name>-light-detail@4x.png` cropped to that rect (in
+    /// view points) for a close look at small glyphs. `build` runs once per
+    /// scheme: views that pick colors from their own `colorScheme` property
+    /// (like `GPUSpinnerNSView`) need it set, since the appearance alone does
+    /// not reach them.
+    @MainActor
+    static func render(name: String, detail: NSRect? = nil, build: (ColorScheme) -> NSView) {
+        for (label, scheme, appearanceName) in [
+            ("light", ColorScheme.light, NSAppearance.Name.aqua),
+            ("dark", ColorScheme.dark, NSAppearance.Name.darkAqua),
+        ] {
+            let appearance = NSAppearance(named: appearanceName)!
+            var view: NSView?
+            appearance.performAsCurrentDrawingAppearance { view = build(scheme) }
+            guard let view else { continue }
+            write(view, appearance: appearance, scale: 2, rect: view.bounds, file: "\(name)-\(label)@2x.png")
+            if let detail, label == "light" {
+                write(view, appearance: appearance, scale: 4, rect: detail, file: "\(name)-\(label)-detail@4x.png")
+            }
+        }
+    }
+
+    @MainActor
+    private static func write(_ view: NSView, appearance: NSAppearance, scale: CGFloat, rect: NSRect, file: String) {
+        view.appearance = appearance
+        var data: Data?
+        appearance.performAsCurrentDrawingAppearance {
+            layoutAll(view)
+            guard let rep = NSBitmapImageRep(
+                bitmapDataPlanes: nil,
+                pixelsWide: Int(rect.width * scale),
+                pixelsHigh: Int(rect.height * scale),
+                bitsPerSample: 8,
+                samplesPerPixel: 4,
+                hasAlpha: true,
+                isPlanar: false,
+                colorSpaceName: .deviceRGB,
+                bytesPerRow: 0,
+                bitsPerPixel: 0
+            ) else { return }
+            rep.size = rect.size
+            view.cacheDisplay(in: rect, to: rep)
+            data = rep.representation(using: .png, properties: [:])
+        }
+        let url = outputDirectory.appendingPathComponent(file)
+        guard let data else {
+            fail("could not encode \(url.path) as PNG")
+        }
+        do {
+            try data.write(to: url)
+            print(url.path)
+        } catch {
+            fail("could not write \(url.path): \(error)")
+        }
+    }
+
+    private static func fail(_ message: String) -> Never {
+        FileHandle.standardError.write("ui-lab: \(message)\n".data(using: .utf8)!)
+        exit(1)
+    }
+
+    @MainActor
+    private static func layoutAll(_ view: NSView) {
+        view.needsLayout = true
+        view.layoutSubtreeIfNeeded()
+        view.subviews.forEach(layoutAll)
+    }
+
+    /// A flipped container: frames are laid out top-down like the sidebar cells.
+    final class Canvas: NSView {
+        var fill: NSColor?
+        override var isFlipped: Bool { true }
+        override func draw(_ dirtyRect: NSRect) {
+            if let fill {
+                fill.setFill()
+                dirtyRect.fill()
+            }
+        }
+    }
+}

scripts/ui-lab/harnesses/gpu-spinner.swift

@@ -0,0 +1,35 @@
+// ui-lab: source Sources/Sidebar/GPUSpinnerStyle.swift
+// ui-lab: source Sources/Sidebar/GPUSpinnerNSView.swift
+// ui-lab: shim SidebarAppearanceColorResolver
+//
+// The sidebar loading spinner in each style, at the sizes rows use (12 pt,
+// 16 pt). A still frame: the rotation is a Core Animation loop that ui-lab
+// does not advance.
+
+import AppKit
+
+UILab.main {
+    let styles: [GPUSpinnerStyle] = [.macOSSpokes, .arc]
+    let sizes: [CGFloat] = [12, 16]
+    let cell: CGFloat = 28
+    let bounds = NSRect(x: 0, y: 0, width: cell * CGFloat(sizes.count) + 16, height: cell * CGFloat(styles.count) + 16)
+    UILab.render(name: "gpu-spinner", detail: bounds) { scheme in
+        let canvas = UILab.Canvas(frame: bounds)
+        canvas.fill = .windowBackgroundColor
+        for (row, style) in styles.enumerated() {
+            for (column, size) in sizes.enumerated() {
+                let spinner = GPUSpinnerNSView(frame: NSRect(
+                    x: 8 + CGFloat(column) * cell + (cell - size) / 2,
+                    y: 8 + CGFloat(row) * cell + (cell - size) / 2,
+                    width: size,
+                    height: size
+                ))
+                spinner.style = style
+                // The spinner colors itself from this, not the appearance.
+                spinner.colorScheme = scheme
+                canvas.addSubview(spinner)
+            }
+        }
+        return canvas
+    }
+}

scripts/ui-lab/shims/RenderableSystemSymbol.swift

@@ -0,0 +1,31 @@
+import AppKit
+import SwiftUI
+
+/// ui-lab stand-in for Sources/RenderableSystemSymbol.swift's AppKit path:
+/// the same symbol configuration (point size, weight, monochrome, template),
+/// without the app's caches and font-magnification plumbing.
+enum RenderableSystemSymbol {
+    @MainActor
+    static func configuredAppKitImage(systemName: String, pointSize: CGFloat, weight: Font.Weight? = nil) -> NSImage? {
+        guard let base = NSImage(systemSymbolName: systemName, accessibilityDescription: nil) else { return nil }
+        let configuration = NSImage.SymbolConfiguration(pointSize: pointSize, weight: nsWeight(weight))
+            .applying(.preferringMonochrome())
+        let image = base.withSymbolConfiguration(configuration) ?? base
+        image.isTemplate = true
+        return image
+    }
+
+    private static func nsWeight(_ weight: Font.Weight?) -> NSFont.Weight {
+        switch weight {
+        case .ultraLight?: return .ultraLight
+        case .thin?: return .thin
+        case .light?: return .light
+        case .medium?: return .medium
+        case .semibold?: return .semibold
+        case .bold?: return .bold
+        case .heavy?: return .heavy
+        case .black?: return .black
+        default: return .regular
+        }
+    }
+}

scripts/ui-lab/shims/SidebarAppearanceColorResolver.swift

@@ -0,0 +1,16 @@
+import AppKit
+import SwiftUI
+
+/// ui-lab stand-in for Sources/Sidebar/SidebarAppearanceSupport.swift's
+/// resolver: resolves a dynamic color under the given scheme's appearance.
+struct SidebarAppearanceColorResolver {
+    func resolvedColor(_ color: NSColor, for colorScheme: ColorScheme, opacity: CGFloat? = nil) -> NSColor {
+        let appearance = NSAppearance(named: colorScheme == .dark ? .darkAqua : .aqua)!
+        var resolved = color
+        appearance.performAsCurrentDrawingAppearance {
+            resolved = color.usingColorSpace(.deviceRGB) ?? color
+        }
+        guard let opacity else { return resolved }
+        return resolved.withAlphaComponent(max(0, min(opacity, 1)))
+    }
+}

scripts/ui-lab/ui-lab.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Render cmux view code to PNGs in seconds, without building the app.
+
+A harness is a Swift file whose top-level code builds views and hands them to
+`UILab.render`. Its header names the app sources to compile with it:
+
+    // ui-lab: source Sources/Sidebar/GPUSpinnerNSView.swift
+    // ui-lab: shim SidebarAppearanceColorResolver
+
+`source` paths are repo-relative; `shim` names a file in scripts/ui-lab/shims/
+standing in for an app type the sources use. Sources are compiled as one
+module with plain `swiftc` (their `import Cmux*` lines are dropped), so a
+harness can only pull in files without package or app dependencies beyond
+its shims. Keep view code that way when you want it here.
+
+    scripts/ui-lab/ui-lab.py scripts/ui-lab/harnesses/gpu-spinner.swift
+    scripts/ui-lab/ui-lab.py <harness> --watch     # re-render on every save
+    scripts/ui-lab/ui-lab.py <harness> --out DIR
+
+Each render writes light and dark PNGs at 2x, plus a 4x crop for detail, and
+prints their paths. The binary is cached by input hash, so an unchanged
+re-run only renders. This is a design loop, not proof: the CI UI tests
+(`scripts/ui-test`) still check the real app.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+LAB = Path(__file__).resolve().parent
+DIRECTIVE = re.compile(r"^//\s*ui-lab:\s*(source|shim)\s+(\S+)\s*$")
+# `import CmuxFoo`, `@testable import CmuxFoo`, `import struct CmuxFoo.Bar`...
+# Blanked, not deleted, so compiler line numbers still match the real file.
+PACKAGE_IMPORT = re.compile(
+    r"^[ \t]*(?:@\w+[ \t]+)*(?:(?:public|internal|package|private|fileprivate)[ \t]+)?"
+    r"import[ \t]+(?:(?:struct|class|enum|protocol|typealias|func|var|let|actor)[ \t]+)?Cmux\w*[^\n]*$",
+    re.M,
+)
+CACHE_DAYS = 14
+CACHE = Path(os.environ.get("CMUX_UI_LAB_CACHE", Path.home() / "Library/Caches/cmux-ui-lab"))
+
+
+def inputs(harness: Path) -> list[Path]:
+    """The Swift files one harness compiles: support, shims, sources, harness."""
+    files = [LAB / "UILab.swift"]
+    for line in harness.read_text().splitlines():
+        match = DIRECTIVE.match(line.strip())
+        if not match:
+            continue
+        kind, value = match.groups()
+        path = LAB / "shims" / f"{value}.swift" if kind == "shim" else ROOT / value
+        if not path.exists():
+            raise SystemExit(f"ui-lab: {kind} {value} not found at {path}")
+        files.append(path)
+    return files + [harness]
+
+
+def toolchain() -> str:
+    """What else decides the binary: compiler, SDK and developer dir."""
+    try:
+        version = subprocess.run(["swiftc", "--version"], capture_output=True, text=True, check=True).stdout
+        sdk = subprocess.run(["xcrun", "--show-sdk-path"], capture_output=True, text=True).stdout
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise SystemExit(f"ui-lab: swiftc is not available ({error}); install Xcode or the command line tools")
+    return version + sdk + os.environ.get("DEVELOPER_DIR", "")
+
+
+def prune_cache() -> None:
+    cutoff = time.time() - CACHE_DAYS * 86400
+    for entry in CACHE.glob("*/lab"):
+        try:
+            if entry.stat().st_mtime < cutoff:
+                shutil.rmtree(entry.parent, ignore_errors=True)
+        except OSError:
+            pass
+
+
+def build(harness: Path) -> Path:
+    files = inputs(harness)
+    digest = hashlib.sha256(Path(__file__).read_bytes())  # flags and source rewriting
+    for path in files:
+        digest.update(str(path).encode())
+        digest.update(path.read_bytes())
+    digest.update(toolchain().encode())
+    binary = CACHE / digest.hexdigest()[:16] / "lab"
+    if binary.exists():
+        os.utime(binary)
+        return binary
+    prune_cache()
+
+    work = Path(tempfile.mkdtemp(prefix="cmux-ui-lab-"))
+    try:
+        compiled = []
+        for index, path in enumerate(files):
+            text = path.read_text()
+            if path != harness:
+                # One module: package imports resolve to shims or nothing.
+                text = PACKAGE_IMPORT.sub("", text)
+            name = "main.swift" if path == harness else f"{index:02d}-{path.name}"
+            (work / name).write_text(text)
+            compiled.append(str(work / name))
+        binary.parent.mkdir(parents=True, exist_ok=True)
+        started = time.monotonic()
+        # Build beside the cache entry, then rename: concurrent runs of the
+        # same harness never see a half-written binary.
+        partial = work / "lab"
+        result = subprocess.run(
+            ["swiftc", "-Onone", "-swift-version", "5", "-o", str(partial), *compiled],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            # Point errors at the real files, not the temp copies.
+            output = result.stderr
+            for index, path in enumerate(files):
+                name = "main.swift" if path == harness else f"{index:02d}-{path.name}"
+                output = output.replace(str(work / name), str(path))
+            sys.stderr.write(output)
+            raise SystemExit("ui-lab: compile failed")
+        shutil.copy2(partial, binary.with_name(f"lab.{os.getpid()}"))
+        os.replace(binary.with_name(f"lab.{os.getpid()}"), binary)
+        print(f"ui-lab: compiled {len(files)} files in {time.monotonic() - started:.1f}s", file=sys.stderr)
+        return binary
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def render(harness: Path, out: Path) -> None:
+    binary = build(harness)
+    out.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run([str(binary), str(out)], capture_output=True, text=True)
+    sys.stdout.write(result.stdout)
+    sys.stderr.write(result.stderr)
+    if result.returncode != 0:
+        raise SystemExit(f"ui-lab: harness exited {result.returncode}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("harness", type=Path)
+    parser.add_argument("--out", type=Path, help="default: $TMPDIR/cmux-ui-lab/<harness name>")
+    parser.add_argument("--watch", action="store_true", help="re-render whenever an input changes")
+    args = parser.parse_args(argv)
+
+    harness = args.harness.resolve()
+    out = args.out or Path(tempfile.gettempdir()) / "cmux-ui-lab" / harness.stem
+    try:
+        render(harness, out)
+    except SystemExit as error:
+        if not args.watch:
+            raise
+        print(error, file=sys.stderr)
+    if not args.watch:
+        return 0
+
+    def stamp() -> tuple[float, ...]:
+        try:
+            return tuple(path.stat().st_mtime for path in inputs(harness))
+        except (OSError, SystemExit):
+            return ()
+
+    last = stamp()
+    print("ui-lab: watching; Ctrl-C to stop", file=sys.stderr)
+    while True:
+        time.sleep(0.4)
+        current = stamp()
+        if current and current != last:
+            last = current
+            try:
+                render(harness, out)
+            except SystemExit as error:
+                print(error, file=sys.stderr)
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        sys.exit(130)