rork-xcode 0.1.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/rorkai/rork-xcode/actions/workflows/ci.yml/badge.svg)](https://github.com/rorkai/rork-xcode/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/rork-xcode)](https://www.npmjs.com/package/rork-xcode)
 
-The [fastest](#performance) zero-dependency Xcode project (`project.pbxproj`) parser and builder for any JavaScript runtime: browsers, Node.js, Bun, Electron, Cloudflare Workers, and React Native.
+The [fastest](#performance) zero-dependency Xcode project (`project.pbxproj`) parser, builder, and object model for any JavaScript runtime: browsers, Node.js, Bun, Electron, Cloudflare Workers, and React Native. [Scheme files](#schemes) (`.xcscheme`) are covered with the same round-trip guarantees.
 
 ```ts
 import { parsePbxproj, buildPbxproj } from "rork-xcode";
@@ -85,6 +85,183 @@ try {
 
 Booleans are rejected on purpose. The format has no boolean notation (Xcode models flags as the strings `"YES"` and `"NO"`), so writing one would produce a value Xcode misreads.
 
+## Object model
+
+`XcodeProject` gives typed, mutable access to a parsed project. It is a set of lightweight views over the plain parsed document: all state lives in the document itself, a view holds only an object id, and `build()` serializes whatever the document currently says in Xcode's canonical layout. Model calls and direct dictionary access compose freely, and the model adds no measurable overhead over the raw functions (`XcodeProject.parse` and `project.build()` benchmark identically to `parsePbxproj` and `buildPbxproj`).
+
+This document-first design is deliberate, and the library's guarantees fall out of it. There is no inflate step on parse and no deflate step on build, so an untouched project rebuilds byte-identically and an edit changes only the entries it touches. Combined with deterministic identifiers, the same edit sequence produces the same bytes on every run, on every runtime.
+
+```ts
+import { XcodeProject } from "rork-xcode";
+
+const project = XcodeProject.parse(pbxprojText);
+const text = project.build();
+```
+
+### Targets and build settings
+
+`getBuildSetting` resolves hierarchically the way Xcode does: the target's default configuration first, then the project-level configuration. Writes go to every configuration of the target, so Debug and Release stay consistent.
+
+```ts
+const app = project.findMainAppTarget("ios"); // "macos" | "tvos" | "watchos" | "visionos"
+app?.getBuildSetting("PRODUCT_BUNDLE_IDENTIFIER"); // "com.example.app"
+app?.getBuildSetting("SDKROOT"); // inherited from the project configuration
+app?.setBuildSetting("MARKETING_VERSION", "1.2.0");
+app?.removeBuildSetting("CODE_SIGN_IDENTITY");
+
+for (const target of project.nativeTargets()) {
+  console.log(target.name, target.productType);
+}
+```
+
+`project.targets()` returns every target kind. Aggregate targets (`PBXAggregateTarget`) and legacy external-build-tool targets (`PBXLegacyTarget`) share the full target surface, from configurations and build settings to phases and dependency wiring.
+
+```ts
+for (const target of project.targets()) {
+  if (target instanceof LegacyTarget) {
+    console.log(target.name, target.buildToolPath);
+  }
+}
+```
+
+### Scaffolding a target
+
+`addNativeTarget` creates the configurations, the product reference in the Products group, and the standard Sources, Frameworks, and Resources phases. Dependencies wire the container proxy pair Xcode uses; `embed` picks the right copy-files phase and destination for the product type (foundation extensions, ExtensionKit extensions, App Clips, watch content).
+
+```ts
+import { ProductType } from "rork-xcode";
+
+const widget = project.addNativeTarget({
+  name: "DemoWidget",
+  productType: ProductType.appExtension,
+  buildSettings: { PRODUCT_BUNDLE_IDENTIFIER: "com.example.app.widget" },
+});
+widget.setBuildSetting("IPHONEOS_DEPLOYMENT_TARGET", "18.0");
+
+app.addDependency(widget);
+app.embed(widget); // "Embed Foundation Extensions", dstSubfolderSpec 13
+
+// Xcode 16 synchronized folder, with the scaffolded Info.plist excluded
+// so the build does not copy it twice.
+const folder = widget.addSyncGroup("DemoWidget");
+folder.addMembershipExceptions(widget, ["Info.plist"]);
+```
+
+### Swift packages
+
+```ts
+const pkg = project.addSwiftPackage({
+  repositoryURL: "https://github.com/example/example-kit",
+  requirement: { kind: "upToNextMajorVersion", minimumVersion: "2.0.0" },
+});
+
+// Wires the product dependency and its Frameworks-phase build file.
+app.addSwiftPackageProduct({ productName: "ExampleKit", packageReference: pkg });
+
+// Local (path-based) packages and system frameworks work the same way.
+const local = project.addLocalSwiftPackage("Packages/DesignSystem");
+app.addSwiftPackageProduct({ productName: "DesignSystem", packageReference: local });
+app.addSystemFramework("Messages");
+```
+
+### Files, groups, and phases
+
+```ts
+import { Isa } from "rork-xcode";
+
+// Classic (non-synchronized) file management, with nested group creation.
+const mainGroup = project.rootProject.mainGroup();
+const generated = mainGroup?.ensureGroup("Sources/Generated");
+const file = generated?.createFile("Config.swift");
+if (file) app.ensureSourcesPhase().ensureBuildFile(file);
+
+project.findFileReference("Sources/Generated/Config.swift"); // resolves through the group tree
+
+// Phases expose their build files for reorganization, and script phases
+// create with the usual defaults.
+const embedPhase = app.findBuildPhase(Isa.copyFilesBuildPhase, "Embed Foundation Extensions");
+embedPhase?.buildFileIds;
+app.ensureShellScriptPhase("Lint", { shellScript: "lint\n" });
+```
+
+### Validation
+
+Projects rot over time. References outlive the objects they pointed at, orphans pile up, an entry loses its `isa`. `validate()` finds these problems and returns them as data. `pruneOrphans()` deletes everything the root object cannot reach, and it errs on the safe side. If anything still references an object, it stays.
+
+```ts
+for (const issue of project.validate()) {
+  console.warn(issue.kind, issue.message);
+}
+project.pruneOrphans(); // returns the removed ids
+```
+
+### Removal
+
+`removeObject` deletes one object and strips every reference to it from the rest of the document. `removeTarget` composes it into a full teardown: the target's phases and build files, configurations, product reference and its embeddings, dependency objects other targets hold on it, membership exceptions, and synchronized folders no remaining target links. On-disk sources are untouched.
+
+```ts
+const widget = project.findTarget("DemoWidget");
+if (widget) project.removeTarget(widget);
+
+project.referrersOf(app.id); // every object referencing an id, for custom teardowns
+```
+
+### Escape hatch
+
+Every view exposes its raw dictionary, so anything the typed surface does not cover stays one property away, and `project.objects()` iterates every object with its typed view:
+
+```ts
+app.properties["productName"] = "RenamedApp";
+
+for (const [id, object] of project.objects()) {
+  if (object.isa === "PBXShellScriptBuildPhase") {
+    console.log(id, object.getString("name"));
+  }
+}
+```
+
+### Semantics
+
+- **Typed vocabulary, generic fallback.** The typed views cover targets of every kind, groups and variant groups, Xcode 16 synchronized folders and their exception sets, build phases and build rules, Core Data version groups, and cross-project reference proxies. Every other kind is a generic `XcodeObject` with the same read and write access, so nothing in a document is out of reach.
+- **Typed, open property shapes.** Known keys autocomplete (`target.properties.productType`) and the shape stays open, so keys like `INFOPLIST_KEY_*` settings remain first-class. The shapes describe well-formed documents. When reading untrusted input, use the narrowing accessors, which never trust them.
+- **Two verb families.** `add*` wires something to its owner (a dependency, a package, a framework, a synchronized folder) and is idempotent: re-adding returns the existing wiring. `ensure*` returns a structural container, creating it when missing (a build phase, a group chain, the Products group). Both families can therefore run unconditionally in scaffold and repair flows.
+- **Deterministic identifiers.** New objects get ids derived from what they are (`XX` + 20 digest characters + `XX`, from an embedded hash), so programmatic edits are reproducible run to run and diffs stay minimal. Collisions within a document resolve deterministically, and identical edit sequences produce byte-identical documents.
+- **Soft reads, loud writes.** Real-world projects can be malformed, so lookups return `undefined` where a document could omit something. Operations that cannot proceed without structure (no root project object, an unknown product type, a view whose object was deleted) throw `XcodeModelError`.
+- **Identity-mapped views.** Two lookups of the same id return the same instance, so views compare with `===`.
+
+## Schemes
+
+`.xcscheme` files describe how Xcode builds, runs, tests, and archives a target. They are not property lists but a small XML dialect of their own, and `parseXcscheme` and `buildXcscheme` cover it with the same contract as the pbxproj functions: an Xcode-written scheme rebuilds byte for byte, any other input reaches Xcode's canonical layout in one build, and malformed input fails with a typed error carrying line and column.
+
+```ts
+import { buildXcscheme, parseXcscheme, xcschemeElements } from "rork-xcode";
+
+const scheme = parseXcscheme(xcschemeText);
+
+// The tree is plain data: elements with ordered attributes and children.
+for (const reference of xcschemeElements(scheme.root, "BuildableReference")) {
+  reference.attributes["BlueprintName"] = "RenamedApp";
+  reference.attributes["BuildableName"] = "RenamedApp.app";
+  reference.attributes["ReferencedContainer"] = "container:RenamedApp.xcodeproj";
+}
+
+const text = buildXcscheme(scheme);
+```
+
+`createXcscheme` produces the scheme Xcode's own "New Scheme" action writes for an application target, wired to the target's object id from the project document:
+
+```ts
+import { createXcscheme } from "rork-xcode";
+
+const scheme = createXcscheme({
+  appName: "DemoApp",
+  blueprintIdentifier: app.id,
+});
+const text = buildXcscheme(scheme);
+```
+
+Attribute order is preserved and meaningful: the writer emits attributes in insertion order, which is how byte-identical round-trips fall out. Comments are kept, attribute values resolve the character references Xcode writes (`"`, `&`, `
` and friends), and the writer re-escapes them identically.
+
 ## Performance
 
 `rork-xcode` is measured against the pbxproj parsers on npm, [`@bacons/xcode`](https://www.npmjs.com/package/@bacons/xcode) (its `/json` parse/build entry point) and [`xcode`](https://www.npmjs.com/package/xcode) (the long-standing package used by native build tooling), on three documents: two real Xcode-written projects from the test suite and a deterministically generated five-target app with 800 source files. It is the fastest at both operations on every document, with zero dependencies.
@@ -116,9 +293,18 @@ Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0
 - The committed fixture corpus spans project generations from Xcode 3 to Xcode 16, captured from real projects with identifiers neutralized: synchronized folders with both exception-set kinds, classic groups, variant groups, aggregate and legacy targets, reference proxies, build rules, Swift packages, and a ~100 KiB multiplatform framework project.
 - Documents already in current Xcode's layout must round-trip byte for byte; documents from other tool generations must normalize to a byte-stable fixed point with unchanged values.
 - On macOS, the suite cross-validates every fixture and its rebuilt form with `plutil`, Apple's own property list parser and the empirical ground truth for what Apple tooling accepts.
-- A corpus sweep (`pnpm corpus`) walks every Xcode project on the machine, verifies each one parses and reaches a byte-stable fixed point, and cross-validates a sample of parsed values against plutil's own reading.
+- A corpus sweep (`pnpm corpus`) walks every Xcode project and scheme on the machine, verifies each one parses and reaches a byte-stable fixed point, exercises the object model against every project, and cross-validates a sample against plutil's own reading.
 - CI runs the full gate on Linux and macOS, and executes the built artifact on the oldest supported Node to enforce the `engines` floor.
 
+## Releasing
+
+Releases publish to npm from CI with [provenance](https://docs.npmjs.com/generating-provenance-statements) via [trusted publishing](https://docs.npmjs.com/trusted-publishers); no long-lived tokens are stored in the repository.
+
+1. Bump `version` in `package.json` and merge to `main`.
+2. Create a GitHub release with an `X.Y.Z` tag matching the new version.
+3. The release workflow verifies the tag, runs the full gate (including
+   plutil cross-validation on the macOS runner), and publishes.
+
 ## License
 
 Apache-2.0