@swiftbrowser/cli 0.6.7 → 0.8.0

package/README.md

@@ -36,12 +36,15 @@ down), or a plain folder of Swift sources. Options for all of them:
 (with Swift 6.4 and its Swift SDK for WebAssembly): every module of the shim,
 and an archive of each module's objects, in a *kit* under
 `~/.cache/swiftbrowser/kits/` (`SWIFTBROWSER_CACHE` moves the cache). A
-released CLI comes with its kit, @swiftbrowser/kit (23 MB to download) and
-the macros for your machine (@swiftbrowser/kit-linux-x64, -linux-arm64 or
--darwin-arm64, 4 MB): the first build copies it into the cache and checks
-that your toolchain reads its modules. Where it cannot (another host, a
-toolchain whose compiler reads only modules it wrote), or in a checkout of
-this repository, the first build compiles the kit itself, in a minute or two. A kit takes 83 MB: 50 MB of archives, 15 MB of
+released CLI comes with its kit, @swiftbrowser/kit (36 MB to download): the
+first build copies it into the cache and checks that your toolchain reads its
+modules. Its macros (`@Model`, `#Predicate`, `@Entry`) come built as
+WebAssembly, the same files on every host: the toolchain runs them through a
+small launcher in @swiftbrowser/wasm-compiler, under the Node that runs the
+CLI. Where the kit cannot serve (Windows, where the compiler runs no
+launcher script; a toolchain whose compiler reads only modules it wrote), or
+in a checkout of this repository, the first build compiles the kit itself, in
+a minute or two. A kit takes 83 MB: 50 MB of archives, 15 MB of
 modules and the 18 MB macro executable; SwiftPM's scratch path for building
 kits takes 325 MB more.
 Every app built after that, in any project, compiles its own code and
@@ -55,7 +58,54 @@ the toolchain and the SDK, so a change to any of them (a newer
 SwiftPM's scratch path for kits stays in the cache, so that rebuild compiles
 only the modules the change touched, and the three most recent kits are kept.
 `SWIFTBROWSER_KIT=0` builds the shim from its sources in the app's own build
-instead, as before kits. `check` compiles natively and does not use the kit.
+instead, as before kits. A native `check` compiles for the host against the
+shim's sources and does not use the kit.
+
+### The WebAssembly compiler
+
+`--compiler` (or `SWIFTBROWSER_COMPILER`, which the flag overrides) picks
+what compiles the app in `check`, `dev`, `build` and `test` (src/compiler.ts):
+
+| Value | Builds with |
+|---|---|
+| `auto` (the default) | the Swift toolchain when it is installed (it builds faster), else the WebAssembly compiler, saying why |
+| `native` | the Swift toolchain and SwiftPM |
+| `wasm` | the Swift compiler and linker built as WebAssembly (`@swiftbrowser/wasm-compiler`, the tools from `@swiftbrowser/wasm-tools` or `SWIFTBROWSER_WASM_TOOLS`): no Swift install |
+
+So with Swift installed nothing changes, and without it `npx
+@swiftbrowser/cli dev` builds with the npm packages alone, once
+`swiftbrowser doctor --install` has downloaded the Swift SDK for
+WebAssembly's files.
+
+The WebAssembly compiler builds against the kit and needs only the Swift
+SDK for WebAssembly's files: the toolchain's install, or, without a
+toolchain, the CLI's own download (`swiftbrowser doctor --install`, 93 MB
+into the cache; src/wasmSdk.ts). Without a toolchain it uses the released
+kit (@swiftbrowser/kit, checked by type-checking an import of every module)
+and cannot build one. It runs the kit's macros
+built as WebAssembly: @swiftbrowser/kit has them, and a kit made here gets
+them from `swiftbrowser kit --wasm-macros` or the first WebAssembly build
+(with a toolchain; minutes the first time, swift-syntax compiling for
+WebAssembly). `check` type-checks against the kit with it. Package
+dependencies build with it too: without SwiftPM in charge (no toolchain, or
+`--compiler wasm`), the CLI resolves them with git, honouring
+`Package.resolved` (src/resolve.ts; registry packages from their
+registry, src/registry.ts), and runs their manifests with the
+WebAssembly tools (src/manifest.ts; @swiftbrowser/wasm-tools ships SwiftPM's
+PackageDescription for this), caching both. C targets in packages compile
+with clang built as WebAssembly, and package traits are followed; Ice Cubes
+builds this way. A package's macro targets (TCA's) build as WebAssembly
+plugins, swift-syntax compiled for them alone (minutes the first time, then
+cached). The packages' compiled modules are cached too, keyed by their
+inputs (src/moduleCache.ts): a rebuild compiles only what an edit reaches,
+and apps share the modules of the packages they have in common. `test`
+builds with it too: the app as a testable module, each test target against
+it, and a runner like SwiftPM's (XCTest's tests listed from the test
+module's symbol graph, Swift Testing's found as it runs; src/testDiscovery.ts),
+with swift-testing's macros built as WebAssembly. In
+`dev` it compiles unoptimized (`-Onone`, without a DEBUG define, so the app
+behaves as it will in `build`) and keeps the compiled tools between
+rebuilds: a save rebuilds Counter in about 5 s, as SwiftPM does.
 
 Building several apps in a row (a CI job, a script) can compile the
 SwiftBrowser package once for all of them: set `SWIFTBROWSER_BUILD_ROOT` to a
@@ -140,7 +190,8 @@ was released with).
 rebuilds neither from scratch. Each unit-test target is a test target in it
 that depends on the app's. Its files get the same adjustments, along with
 the generated alias file, because a test module imports both Foundation and
-the app. It links the SDK's whole ICU data rather than a trimmed copy.
+the app. It links the SDK's whole ICU data rather than a trimmed copy. The
+WebAssembly compiler builds the same staging without SwiftPM.
 
 ## Foundation
 
@@ -232,6 +283,7 @@ CI checks.
   "corsProxy": "https://swiftbrowser-cors-proxy.you.workers.dev/",
   "packages": [
     { "url": "https://github.com/twostraws/CodeScanner", "from": "2.5.2", "products": ["CodeScanner"] },
+    { "id": "mona.LinkedList", "from": "1.2.0", "products": ["LinkedList"] },
     { "path": "../Shared", "products": ["SharedKit"] }
   ]
 }
@@ -250,9 +302,14 @@ files) one by one.
 
 `packages` adds Swift packages to the ones the Xcode target links: the only
 way a plain folder of sources depends on one. Each has a `url` with one rule
-(`from`: up to the next major version, `exact`, `branch` or `revision`), or
-a local `path` (relative to the project), and the `products` the app
-imports. They are built as described in "Swift packages".
+(`from`: up to the next major version, `exact`, `branch` or `revision`), a
+package registry's `id` (`scope.name`) with `from` or `exact`, or a local
+`path` (relative to the project), and the `products` the app imports. They
+are built as described in "Swift packages". Registries are configured as
+SwiftPM configures them (`swift package-registry set`):
+`.swiftpm/configuration/registries.json` in the app's folder, then in your
+home folder, with credentials in `~/.netrc`; packages that depend on
+registry packages (`.package(id:)`) find them the same way.
 
 `corsProxy` (or `--cors-proxy <url>` on `dev` and `build`) names a CORS proxy:
 the page retries a cross-origin GET or HEAD the browser refused (the server
@@ -413,6 +470,20 @@ git clone --depth 1 https://github.com/apple/sample-food-truck
 npx @swiftbrowser/cli dev sample-food-truck --target "Food Truck"
 ```
 
+[The Composable Architecture](https://github.com/pointfreeco/swift-composable-architecture)
+builds as it is, with the packages it brings (swift-dependencies,
+swift-navigation, swift-sharing, combine-schedulers and the rest): its
+macros (`@Reducer`, `@ObservableState`, `@DependencyClient`) build as
+plugins, and its packages are copied and built against the shim like any
+other. swift-navigation's UIKit layer builds over the shim's UIKit, whose
+views and view controllers are `NSObject`s with iOS 17's traits; the
+Objective-C target it swizzles view controllers with is the shim's own
+lifecycle hooks here. Code a package keeps for older systems
+(`#if canImport(ObjectiveC)`, CoreFoundation imports, `-ObjC` link flags,
+KVO overrides) is adjusted in its copy (src/appSources.ts, vendor.ts). The
+TCACounter fixture (packages/cli/test/fixtures/apps) is a counter, with
+the versions it was made with pinned in its Package.resolved.
+
 A package SwiftBrowser has a patch for is built from its own sources with
 a few passages replaced first: code that only works with the Objective-C
 runtime and no general adjustment can take. Today that is

package/dist/appSources.d.ts

@@ -0,0 +1,116 @@
+export interface TransformResult {
+    text: string;
+    previewsStripped: number;
+    /** `import Foundation` lines rewritten. */
+    foundationRewrites: number;
+}
+export declare function transformSource(text: string, options?: {
+    bridged?: boolean;
+    optionalRequirements?: ReadonlySet<string>;
+}): TransformResult;
+/**
+ * `configuration.delegateClass = SceneDelegate.self` →
+ * `configuration._setDelegateClass(SceneDelegate.self) { SceneDelegate() }`:
+ * UIKit makes the scene delegate through the Objective-C runtime, and Swift
+ * without it can only make an instance from a metatype through a `required`
+ * initializer (UIKit/SceneDelegates.swift). Same line, so diagnostics keep
+ * their places.
+ */
+export declare function sceneDelegateClasses(text: string): string;
+/**
+ * `as? AnyObject` → `as? _AnyObjectValue` where the file reads a number from
+ * the result: `(dict[key] as? AnyObject)?.doubleValue` looks the member up on
+ * any object through Objective-C (nil where there is none); FoundationBridge's
+ * `_AnyObjectValue` (Selector.swift) has those members, optional likewise, on
+ * the numbers, booleans and strings a dictionary of `Any` holds.
+ */
+export declare function numberCasts(text: string): string;
+/** Whether a source uses the Objective-C runtime's selectors or attributes. */
+export declare function usesObjC(text: string): boolean;
+/**
+ * Whether a source calls POSIX mutex functions. WASI's libc module leaves
+ * `pthread.h` out, so a package that does is built from a copy: there
+ * `#if os(iOS)` holds (Darwin's `os_unfair_lock` branch) and FoundationBridge
+ * declares the mutex functions for the page's single thread (Locks.swift).
+ */
+/**
+ * `unsafeBitCast(Selector(#function), to: UnsafeRawPointer.self)` →
+ * `Selector(#function)._uniquePointer`: the address that stands for the
+ * selector's name (FoundationBridge/Selector.swift), which on Apple
+ * platforms the bit cast gives, the selector being a uniqued pointer.
+ */
+export declare function selectorPointers(text: string): string;
+/** Whether a source imports ObjectiveC, which the SDK does not have on WASI (transformSource). */
+export declare function importsObjectiveC(text: string): boolean;
+/** Whether a source imports Dispatch, which the SDK does not have on WASI (transformSource). */
+export declare function importsDispatch(text: string): boolean;
+/** CoreFoundation's headers need wasi-libc's signal and mman emulations (`WASI_EMULATION_FLAGS`). */
+export declare function importsCoreFoundation(text: string): boolean;
+/** What a Swift module that imports CoreFoundation is compiled with for WASI: the emulations its headers include (the link has their libraries). */
+export declare const WASI_EMULATION_FLAGS: readonly string[];
+export declare function usesPosixMutex(text: string): boolean;
+/**
+ * Objective-C without its runtime (FoundationBridge/Selector.swift). The
+ * browser's Swift has no Objective-C interop, so `@objc` (and the Interface
+ * Builder attributes that imply it) is dropped, and `#selector(handle(_:))`
+ * becomes `Selector(Self.handle(_:), name: "handle(_:)")`: the method itself,
+ * which the target/selector APIs call on their target. A qualified method
+ * (`Type.method`) is used as it is; one of another object
+ * (`#selector(model.refresh)`) is called bound; `getter:`/`setter:`
+ * selectors only have a name, as does a method of three or more arguments
+ * (`navigationController(_:didShow:animated:)`), which target-action never
+ * sends (it passes the sender and the event at most) and code only compares
+ * or asks about (`responds(to:)`). A method the file declares `@MainActor` is
+ * bound to its target in a closure instead,
+ * `Selector(name: "tick", isolated: { (target: Self) in target.tick })`:
+ * Swift 6 rejects naming a main-actor method of a class that is not
+ * `Sendable` unapplied (Gifu's display link proxy).
+ */
+export declare function rewriteObjC(text: string): string;
+/** Replaces every `#Preview …{ … }` block and `PreviewProvider` struct with blank lines of the same count. */
+export declare function stripPreviews(text: string): {
+    text: string;
+    count: number;
+};
+/** Index of the `}` closing the `{` at `open`, skipping strings and comments; -1 when unbalanced. */
+export declare function matchingBrace(text: string, open: number): number;
+/** C-ABI entry points the browser renderer calls; the linker must keep them. */
+export declare const WASM_EXPORTS: string[];
+/** The reconciler recurses once per view; 8 MB of stack like a native thread. */
+export declare const APP_STACK_SIZE: number;
+/**
+ * Locale.current follows the host's choice (SB_LOCALE): the two functions
+ * that hard-code en_001 in swift-foundation are redirected to FoundationBridge.
+ */
+export declare const LOCALE_WRAPS: string[];
+/** The linker flags of the app's target (the manifest's `wasmExports`, without `-Xlinker`). */
+export declare function appLinkerFlags(): string[];
+/** The shim's products the app links: the defaults, SwiftData and the frameworks it imports. */
+export declare function linkedProducts(features: StageFeatures): string[];
+/** What the app's sources use beyond the shim, which decides what the staging links. */
+export interface StageFeatures {
+    /**
+     * Some file imports SwiftData: the app links the SwiftData product (and so
+     * builds its macros, against swift-syntax), and the generated file routes
+     * `#Predicate` to SwiftData's copy of the macro.
+     */
+    swiftData: boolean;
+    /** The stand-in frameworks (StoreKit, CoreLocation, LocalAuthentication, CoreML, PhotosUI, CoreImage, UserNotifications, …) some file imports; each is linked. */
+    frameworks: readonly string[];
+}
+/** The features `sources` (their text) call for. */
+export declare function featuresOf(sources: readonly string[]): StageFeatures;
+/** The staged file that settles names declared by both the shim and Foundation. */
+export declare const FULL_FOUNDATION_FILE = "_SwiftBrowserFoundation.swift";
+/**
+ * The app imports both the shim and Foundation, and both declare a few names
+ * (a module does not shadow another's declarations, only the current module's
+ * do). A typealias in the app module does: these point the shared names at
+ * the shim's types (what its `frame(width:)` and friends take) and at
+ * FoundationBridge's `Timer` and `RunLoop`, which Foundation lacks on WASI
+ * (`RunLoop` is marked unavailable, its `Timer` needs CFRunLoop and does not
+ * link).
+ */
+export declare function fullFoundationSource(features?: StageFeatures, declared?: ReadonlySet<string>): string;
+/** The type names a module's sources declare at the top level (lines that start with the declaration). */
+export declare function declaredTypeNames(sources: readonly string[]): Set<string>;