@xcodekit/xcode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgenii Mozharovskii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# @xcodekit/xcode
+
+A fast, native Xcode `.pbxproj` parser and serializer for Node.js, written in Rust.
+
+Drop-in replacement for the low-level API of [`@bacons/xcode`](https://github.com/EvanBacon/xcode) — same `parse()` and `build()` interface, **2-12x faster parsing**, byte-identical output, shipped as a single native binary per platform.
+
+## Install
+
+```bash
+npm install @xcodekit/xcode
+```
+
+Platform-specific binaries are installed automatically via `optionalDependencies`.
+
+## Quick Start
+
+```js
+import { parse, build } from "@xcodekit/xcode";
+import { readFileSync, writeFileSync } from "fs";
+
+// Parse a .pbxproj file
+const text = readFileSync("project.pbxproj", "utf8");
+const project = parse(text);
+
+// Modify it
+project.objects["YOUR_UUID"] = {
+  isa: "PBXFileReference",
+  path: "NewFile.swift",
+  sourceTree: "<group>",
+};
+
+// Write it back
+const output = build(project);
+writeFileSync("project.pbxproj", output);
+```
+
+## API
+
+### Low-Level (JSON)
+
+#### `parse(text: string): object`
+
+Parse a `.pbxproj` string into a JSON-compatible object. Matches the output of `@bacons/xcode/json`'s `parse()`.
+
+#### `build(project: object): string`
+
+Serialize a JSON object back to `.pbxproj` format. Produces byte-identical output to `@bacons/xcode/json`'s `build()`.
+
+#### `buildFromJSON(json: string): string`
+
+Same as `build()` but accepts `JSON.stringify(project)` directly. Faster because it avoids napi's recursive JS-to-Rust object marshalling.
+
+```js
+const output = buildFromJSON(JSON.stringify(project));
+```
+
+#### `parseAndBuild(text: string): string`
+
+Parse and immediately re-serialize. Stays entirely in Rust with zero JS/Rust marshalling — the fastest possible round-trip path.
+
+```js
+const output = parseAndBuild(readFileSync("project.pbxproj", "utf8"));
+```
+
+### High-Level (XcodeProject)
+
+#### `XcodeProject.open(filePath: string): XcodeProject`
+
+Open and parse a `.pbxproj` file from disk.
+
+```js
+import { XcodeProject } from "@xcodekit/xcode";
+
+const project = XcodeProject.open("ios/MyApp.xcodeproj/project.pbxproj");
+
+// Properties
+project.archiveVersion; // 1
+project.objectVersion;  // 46
+project.filePath;       // the path it was opened from
+
+// Targets
+const targets = project.getNativeTargets(); // UUID[]
+const mainApp = project.findMainAppTarget("ios"); // UUID | null
+
+// Build settings
+project.getBuildSetting(targetUuid, "PRODUCT_BUNDLE_IDENTIFIER");
+project.setBuildSetting(targetUuid, "SWIFT_VERSION", "5.0");
+project.removeBuildSetting(targetUuid, "CODE_SIGN_IDENTITY");
+
+// Serialize
+const pbxproj = project.toBuild(); // string
+const json = project.toJSON();     // object
+
+// Write back to disk
+project.save();
+
+// Deterministic UUID generation
+const uuid = project.getUniqueId("my-seed-string"); // 24-char hex
+```
+
+## Performance
+
+Benchmarked on Apple M4 Pro, Node.js v24. Median of 200 iterations.
+
+### Parse
+
+| Fixture | Rust | TypeScript | Speedup |
+|---------|------|-----------|---------|
+| swift-protobuf (257 KB) | 3.7 ms | 43.5 ms | **11.6x** |
+| Cocoa-Application (166 KB) | 3.2 ms | 17.3 ms | **5.5x** |
+| AFNetworking (99 KB) | 1.8 ms | 6.6 ms | **3.8x** |
+| watch (48 KB) | 0.9 ms | 2.1 ms | **2.2x** |
+| project (19 KB) | 0.4 ms | 0.8 ms | **2.2x** |
+
+### Round-Trip (parse + build)
+
+| Fixture | Rust | TypeScript | Speedup |
+|---------|------|-----------|---------|
+| swift-protobuf (257 KB) | 9.1 ms | 63.1 ms | **6.9x** |
+| Cocoa-Application (166 KB) | 8.0 ms | 22.2 ms | **2.8x** |
+| AFNetworking (99 KB) | 4.2 ms | 9.3 ms | **2.2x** |
+| watch (48 KB) | 2.1 ms | 2.7 ms | **1.3x** |
+| project (19 KB) | 0.8 ms | 1.0 ms | **1.2x** |
+
+### parseAndBuild (zero marshalling)
+
+| Fixture | Rust | TypeScript | Speedup |
+|---------|------|-----------|---------|
+| swift-protobuf (257 KB) | 4.6 ms | 62.9 ms | **13.6x** |
+| Cocoa-Application (166 KB) | 3.8 ms | 22.0 ms | **5.8x** |
+| AFNetworking (99 KB) | 1.9 ms | 9.1 ms | **4.9x** |
+| watch (48 KB) | 0.9 ms | 2.6 ms | **2.8x** |
+| project (19 KB) | 0.4 ms | 1.0 ms | **2.7x** |
+
+### Package Size
+
+| | @bacons/xcode | @xcodekit/xcode |
+|-|--------------|-------------------|
+| Unpacked | 1.1 MB | 559 KB |
+| Gzipped | ~400 KB | ~270 KB |
+
+Run benchmarks yourself:
+
+```bash
+make bench        # both Rust + JS
+make bench-rust   # pure Rust (no napi overhead)
+make bench-js     # Rust vs TypeScript head-to-head
+```
+
+## Choosing the Right Function
+
+| Use case | Function | Notes |
+|----------|----------|-------|
+| Parse only | `parse(text)` | 2-12x faster than TS |
+| Build from JS object | `build(obj)` | Fastest on large files (>100 KB) |
+| Build from JSON string | `buildFromJSON(json)` | Faster than `build()` on all sizes |
+| Full round-trip | `parseAndBuild(text)` | Fastest path, zero JS/Rust overhead |
+| Project manipulation | `XcodeProject.open()` | Stays in Rust, use `.toBuild()` to serialize |
+
+## Compatibility
+
+- Full feature parity with `@bacons/xcode/json` (parse/build)
+- 13/13 round-trip fixtures produce **byte-identical** output
+- All escape sequences: standard (`\n`, `\t`, etc.), Unicode (`\Uxxxx`), octal, NeXTSTEP (128 entries)
+- Xcode 16 file system synchronized groups
+- Swift Package Manager references
+- 106 tests (84 Rust + 22 JS)
+
+## Supported Platforms
+
+| Platform | Architecture |
+|----------|-------------|
+| macOS | arm64 (Apple Silicon), x64 (Intel) |
+| Linux | x64 (glibc), arm64 (glibc) |
+| Windows | x64 (MSVC) |
+
+## Development
+
+```bash
+# Prerequisites
+# - Rust toolchain (cargo)
+# - Node.js >= 18
+
+# Install dependencies
+npm install
+
+# Run tests
+make test           # Rust + JS tests
+make test-rust      # Rust tests only (fast, no Node needed)
+make test-js        # JS tests (builds debug binary first)
+
+# Build
+make build          # Release build
+make build-debug    # Debug build (faster compilation)
+
+# Other
+make check          # Type-check without building
+make fmt            # cargo fmt
+make lint           # cargo clippy
+make clean          # Remove all artifacts
+```
+
+### Project Structure
+
+```
+src/
+  lib.rs                  # napi exports: parse, build, XcodeProject
+  parser/
+    lexer.rs              # Fast byte-scanning tokenizer
+    parser.rs             # Recursive descent parser → PlistValue
+    escape.rs             # String unescape (standard, Unicode, octal, NeXTSTEP)
+  writer/
+    serializer.rs         # PlistValue → .pbxproj (section sorting, inline formatting)
+    comments.rs           # UUID → inline comment generation
+    quotes.rs             # String quoting/escaping
+  types/
+    plist.rs              # PlistValue enum (String, Integer, Float, Data, Object, Array)
+    isa.rs                # ISA enum (29 variants)
+    constants.rs          # File type mappings, SDK versions, default build settings
+  project/
+    xcode_project.rs      # High-level project container
+    uuid.rs               # Deterministic MD5-based UUID generation
+    paths.rs              # sourceTree path resolution
+    build_settings.rs     # $(VARIABLE:transform) resolver
+  objects/
+    mod.rs                # PbxObject + PbxObjectExt trait
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,54 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Parse a .pbxproj string into a JSON-compatible object. */
+export declare function parse(text: string): any
+/** Serialize a JSON object back to .pbxproj format. */
+export declare function build(project: any): string
+/**
+ * Serialize a JSON string back to .pbxproj format.
+ * Faster than `build()` — accepts `JSON.stringify(project)` directly,
+ * avoiding napi's recursive JS→Rust object marshalling.
+ */
+export declare function buildFromJSON(json: string): string
+/**
+ * Parse and immediately re-serialize a .pbxproj string.
+ * Fastest path — stays entirely in Rust, zero JS↔Rust marshalling.
+ */
+export declare function parseAndBuild(text: string): string
+/** XcodeProject class for high-level API. */
+export declare class XcodeProject {
+  /** Open and parse a .pbxproj file from disk. */
+  static open(filePath: string): XcodeProject
+  /** Convert the project to a JSON-compatible object. */
+  toJSON(): any
+  /** Serialize the project back to .pbxproj format. */
+  toBuild(): string
+  /** Write the project back to its original file. */
+  save(): void
+  /** Get the file path this project was loaded from. */
+  get filePath(): string | null
+  /** Get the archive version. */
+  get archiveVersion(): number
+  /** Get the object version. */
+  get objectVersion(): number
+  /** Get all native target UUIDs. */
+  getNativeTargets(): Array<string>
+  /** Get a build setting value from a target. */
+  getBuildSetting(targetUuid: string, key: string): any
+  /** Set a build setting on all configurations for a target. */
+  setBuildSetting(targetUuid: string, key: string, value: string): boolean
+  /** Remove a build setting from all configurations for a target. */
+  removeBuildSetting(targetUuid: string, key: string): boolean
+  /**
+   * Find orphaned references (UUIDs referenced but not present in objects).
+   * Returns array of { referrerUuid, referrerIsa, property, orphanUuid }.
+   */
+  findOrphanedReferences(): Array<any>
+  /** Find the main app target UUID. */
+  findMainAppTarget(platform?: string | undefined | null): string | null
+  /** Generate a unique UUID. */
+  getUniqueId(seed: string): string
+}

package/index.js

@@ -0,0 +1,319 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'xcode.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.android-arm64.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'xcode.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'xcode.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'xcode.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'xcode.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'xcode.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./xcode.darwin-universal.node')
+      } else {
+        nativeBinding = require('@xcodekit/xcode-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'xcode.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.darwin-x64.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'xcode.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'xcode.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./xcode.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@xcodekit/xcode-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'xcode.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./xcode.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@xcodekit/xcode-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'xcode.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./xcode.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@xcodekit/xcode-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { parse, build, buildFromJSON, parseAndBuild, XcodeProject } = nativeBinding
+
+module.exports.parse = parse
+module.exports.build = build
+module.exports.buildFromJSON = buildFromJSON
+module.exports.parseAndBuild = parseAndBuild
+module.exports.XcodeProject = XcodeProject

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@xcodekit/xcode",
+  "version": "0.1.0",
+  "description": "Parse, manipulate, and serialize Xcode .pbxproj files — native Rust rewrite",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "xcode",
+    "triples": {
+      "defaults": true,
+      "additional": [
+        "aarch64-apple-darwin",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "license": "MIT",
+  "optionalDependencies": {
+    "@xcodekit/xcode-darwin-arm64": "0.1.0",
+    "@xcodekit/xcode-darwin-x64": "0.1.0",
+    "@xcodekit/xcode-linux-arm64-gnu": "0.1.0",
+    "@xcodekit/xcode-linux-x64-gnu": "0.1.0",
+    "@xcodekit/xcode-win32-x64-msvc": "0.1.0"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "ava": "^6.0.0"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "ava",
+    "universal": "napi universal",
+    "version": "napi version"
+  },
+  "ava": {
+    "timeout": "60000"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "types.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nickmozharovsky/xcode"
+  },
+  "keywords": [
+    "xcode",
+    "pbxproj",
+    "ios",
+    "apple",
+    "parser",
+    "native",
+    "napi",
+    "rust"
+  ]
+}

package/types.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Supplemental type definitions for @xcodekit/xcode.
+ *
+ * These provide rich types for the parsed .pbxproj JSON structure
+ * beyond what napi-rs auto-generates.
+ */
+
+/** ISA types for all known Xcode project object types. */
+export type ISA =
+  | "PBXBuildFile"
+  | "PBXAppleScriptBuildPhase"
+  | "PBXCopyFilesBuildPhase"
+  | "PBXFrameworksBuildPhase"
+  | "PBXHeadersBuildPhase"
+  | "PBXResourcesBuildPhase"
+  | "PBXShellScriptBuildPhase"
+  | "PBXSourcesBuildPhase"
+  | "PBXRezBuildPhase"
+  | "PBXContainerItemProxy"
+  | "PBXFileReference"
+  | "PBXGroup"
+  | "PBXVariantGroup"
+  | "XCVersionGroup"
+  | "PBXFileSystemSynchronizedRootGroup"
+  | "PBXFileSystemSynchronizedBuildFileExceptionSet"
+  | "PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet"
+  | "PBXNativeTarget"
+  | "PBXAggregateTarget"
+  | "PBXLegacyTarget"
+  | "PBXProject"
+  | "PBXTargetDependency"
+  | "XCBuildConfiguration"
+  | "XCConfigurationList"
+  | "PBXBuildRule"
+  | "PBXReferenceProxy"
+  | "XCSwiftPackageProductDependency"
+  | "XCRemoteSwiftPackageReference"
+  | "XCLocalSwiftPackageReference";
+
+/** A 24-character hexadecimal UUID string. */
+export type UUID = string;
+
+/** Boolean as 0 | 1 integer. */
+export type BoolNumber = 0 | 1;
+
+/** Boolean as YES/NO string. */
+export type BoolString = "YES" | "NO" | "YES_ERROR" | "YES_AGGRESSIVE";
+
+/** Source tree reference types. */
+export type SourceTree =
+  | "BUILT_PRODUCTS_DIR"
+  | "DEVELOPER_DIR"
+  | "SOURCE_ROOT"
+  | "SDKROOT"
+  | "<group>"
+  | "<absolute>";
+
+/** CopyFilesBuildPhase destination subfolder spec. */
+export enum SubFolder {
+  absolutePath = 0,
+  wrapper = 1,
+  executables = 6,
+  resources = 7,
+  frameworks = 10,
+  sharedFrameworks = 11,
+  sharedSupport = 12,
+  plugins = 13,
+  javaResources = 15,
+  productsDirectory = 16,
+}
+
+/** Container item proxy type. */
+export enum ProxyType {
+  targetReference = 1,
+  reference = 2,
+}
+
+/** Common file type UTIs. */
+export type FileType =
+  | "sourcecode.swift"
+  | "sourcecode.c.c"
+  | "sourcecode.c.h"
+  | "sourcecode.c.objc"
+  | "sourcecode.cpp.cpp"
+  | "sourcecode.cpp.objcpp"
+  | "sourcecode.javascript"
+  | "wrapper.application"
+  | "wrapper.framework"
+  | "wrapper.app-extension"
+  | "wrapper.plug-in"
+  | "wrapper.xcframework"
+  | "compiled.mach-o.dylib"
+  | "archive.ar"
+  | "folder.assetcatalog"
+  | "text.plist.xml"
+  | "text.plist.strings"
+  | "text.plist.entitlements"
+  | "text.xcconfig"
+  | "file.storyboard"
+  | "file.xib"
+  | "file.intentdefinition"
+  | "image.png"
+  | "image.jpeg"
+  | "net.daringfireball.markdown"
+  | string;
+
+/** Common product type UTIs. */
+export type ProductType =
+  | "com.apple.product-type.application"
+  | "com.apple.product-type.application.on-demand-install-capable"
+  | "com.apple.product-type.app-extension"
+  | "com.apple.product-type.bundle"
+  | "com.apple.product-type.framework"
+  | "com.apple.product-type.library.dynamic"
+  | "com.apple.product-type.library.static"
+  | "com.apple.product-type.tool"
+  | "com.apple.product-type.unit-test-bundle"
+  | "com.apple.product-type.ui-testing-bundle"
+  | "com.apple.product-type.application.watchapp"
+  | "com.apple.product-type.application.watchapp2"
+  | "com.apple.product-type.watchkit-extension"
+  | "com.apple.product-type.extensionkit-extension"
+  | string;
+
+/** Build settings dictionary. */
+export interface BuildSettings {
+  ALWAYS_SEARCH_USER_PATHS?: BoolString;
+  ASSETCATALOG_COMPILER_APPICON_NAME?: string;
+  CLANG_ENABLE_MODULES?: BoolString;
+  CLANG_ENABLE_OBJC_ARC?: BoolString;
+  CODE_SIGN_ENTITLEMENTS?: string;
+  CODE_SIGN_IDENTITY?: string;
+  CODE_SIGN_STYLE?: "Automatic" | "Manual";
+  CURRENT_PROJECT_VERSION?: string;
+  DEBUG_INFORMATION_FORMAT?: "dwarf" | "dwarf-with-dsym";
+  DEVELOPMENT_TEAM?: string;
+  GCC_OPTIMIZATION_LEVEL?: string;
+  GCC_PREPROCESSOR_DEFINITIONS?: string | string[];
+  GENERATE_INFOPLIST_FILE?: BoolString;
+  INFOPLIST_FILE?: string;
+  INFOPLIST_KEY_CFBundleDisplayName?: string;
+  IPHONEOS_DEPLOYMENT_TARGET?: string;
+  MACOSX_DEPLOYMENT_TARGET?: string;
+  TVOS_DEPLOYMENT_TARGET?: string;
+  WATCHOS_DEPLOYMENT_TARGET?: string;
+  MARKETING_VERSION?: string;
+  PRODUCT_BUNDLE_IDENTIFIER?: string;
+  PRODUCT_NAME?: string;
+  SWIFT_VERSION?: string;
+  TARGETED_DEVICE_FAMILY?: string;
+  [key: string]: string | string[] | number | undefined;
+}
+
+/** Base object with isa field. */
+export interface PBXObjectBase {
+  isa: ISA;
+  [key: string]: any;
+}
+
+/** PBXBuildFile object. */
+export interface PBXBuildFile extends PBXObjectBase {
+  isa: "PBXBuildFile";
+  fileRef?: UUID;
+  productRef?: UUID;
+  settings?: Record<string, any>;
+  platformFilter?: string;
+  platformFilters?: string[];
+}
+
+/** PBXFileReference object. */
+export interface PBXFileReference extends PBXObjectBase {
+  isa: "PBXFileReference";
+  fileEncoding?: number;
+  lastKnownFileType?: FileType;
+  explicitFileType?: FileType;
+  includeInIndex?: BoolNumber;
+  name?: string;
+  path?: string;
+  sourceTree?: SourceTree;
+}
+
+/** PBXGroup object. */
+export interface PBXGroup extends PBXObjectBase {
+  isa: "PBXGroup";
+  children: UUID[];
+  name?: string;
+  path?: string;
+  sourceTree?: SourceTree;
+}
+
+/** Build phase (shared fields for all 8 types). */
+export interface AbstractBuildPhase extends PBXObjectBase {
+  buildActionMask?: number;
+  files: UUID[];
+  runOnlyForDeploymentPostprocessing?: BoolNumber;
+}
+
+/** PBXNativeTarget object. */
+export interface PBXNativeTarget extends PBXObjectBase {
+  isa: "PBXNativeTarget";
+  buildConfigurationList: UUID;
+  buildPhases: UUID[];
+  buildRules: UUID[];
+  dependencies: UUID[];
+  name: string;
+  productName?: string;
+  productReference?: UUID;
+  productType: ProductType;
+  packageProductDependencies?: UUID[];
+  fileSystemSynchronizedGroups?: UUID[];
+}
+
+/** PBXProject (root object). */
+export interface PBXProject extends PBXObjectBase {
+  isa: "PBXProject";
+  buildConfigurationList: UUID;
+  compatibilityVersion: string;
+  developmentRegion: string;
+  hasScannedForEncodings: BoolNumber;
+  knownRegions: string[];
+  mainGroup: UUID;
+  productRefGroup?: UUID;
+  projectDirPath: string;
+  projectRoot: string;
+  targets: UUID[];
+  packageReferences?: UUID[];
+  attributes?: {
+    LastSwiftUpdateCheck?: string;
+    LastUpgradeCheck?: string;
+    TargetAttributes?: Record<UUID, Record<string, any>>;
+    [key: string]: any;
+  };
+}
+
+/** XCBuildConfiguration object. */
+export interface XCBuildConfiguration extends PBXObjectBase {
+  isa: "XCBuildConfiguration";
+  name: string;
+  buildSettings: BuildSettings;
+  baseConfigurationReference?: UUID;
+}
+
+/** XCConfigurationList object. */
+export interface XCConfigurationList extends PBXObjectBase {
+  isa: "XCConfigurationList";
+  buildConfigurations: UUID[];
+  defaultConfigurationIsVisible?: BoolNumber;
+  defaultConfigurationName?: string;
+}
+
+/** The top-level parsed .pbxproj structure. */
+export interface ParsedProject {
+  archiveVersion: number;
+  classes: Record<string, any>;
+  objectVersion: number;
+  objects: Record<UUID, PBXObjectBase>;
+  rootObject: UUID;
+}