# @swiftbrowser/xcodeproj

Reads Xcode projects without Xcode: a pure-TypeScript parser for `project.pbxproj`
(Node built-ins only) that answers the questions a CLI has about an iOS app:
which targets exist, which Swift files and asset catalogs they compile, and what
their build settings are.

```ts
import { findXcodeProjects, readXcodeProject } from '@swiftbrowser/xcodeproj';

const [xcodeproj] = findXcodeProjects(process.cwd()); // ./*.xcodeproj, else one level down
const project = readXcodeProject(xcodeproj);
const [app] = project.appTargets(); // targets whose product is an application

app.name; // 'GuessTheFlag'
app.productName; // PRODUCT_NAME with $(TARGET_NAME) resolved
app.bundleIdentifier; // PRODUCT_BUNDLE_IDENTIFIER
app.displayName; // INFOPLIST_KEY_CFBundleDisplayName, else CFBundleDisplayName from INFOPLIST_FILE
app.appIconName; // ASSETCATALOG_COMPILER_APPICON_NAME
app.swiftVersion; // SWIFT_VERSION
app.deploymentTarget; // IPHONEOS_DEPLOYMENT_TARGET
app.sources; // absolute paths of the .swift files, in navigator order
app.models; // the Core ML models (.mlmodel, .mlpackage) it compiles
app.resources; // absolute paths of the Resources build phase entries
app.assetCatalogs; // the *.xcassets among them (and in synchronized folders)
app.dependencies; // names of target dependencies
app.packageProducts; // Swift package products the target links
app.packageDependencies; // the same, each with its package (URL and version rule, or local path)
project.packages; // the project's Swift package references
app.settings('Release'); // merged build settings for a configuration
```

## API

- `readXcodeProject(xcodeprojPath)` parses `<xcodeprojPath>/project.pbxproj` and
  returns an `XcodeProject`: `path`, `root` (the directory containing the
  bundle, what `$(SRCROOT)` means), `objectVersion`, `targets` (every
  `PBXNativeTarget`), `packages` (its `XCRemoteSwiftPackageReference`s, with
  the dependency rule, and `XCLocalSwiftPackageReference`s, with the absolute
  path; each with SwiftPM's identity, see `packageIdentity`) and `appTargets()`.
- `parsePbxproj(text)` returns the raw object graph: `{ objectVersion,
  rootObject, objects }`, where each object has an `isa` plus arbitrary fields
  (strings, arrays, nested dictionaries). `parseOldStylePlist(text)` parses any
  old-style property list fragment.
- `xcodeProjectFromDocument(doc, xcodeprojPath)` interprets an already parsed
  document as the project at that path.
- `findXcodeProjects(dir)` lists the `*.xcodeproj` bundles directly in `dir`,
  else one level down (sorted), skipping `Pods/`, `Carthage/`, `DerivedData/`,
  `.build/`, `node_modules/` and dot-directories.
- `parseXmlPlist(text)` is the minimal XML plist reader used for `Info.plist`.

## How paths are resolved

A file's absolute path is the project root plus the chain of group `path`s
leading to it, following each object's `sourceTree`: `<group>` is relative to
the parent group, `SOURCE_ROOT` to the root, `<absolute>` is absolute; others
(`BUILT_PRODUCTS_DIR`, `SDKROOT`, ...) fall back to the root. Groups without a
`path` contribute nothing. Build phase files are listed in the order of the
group tree (what the Xcode navigator shows), not the arbitrary order of the
build phase. Paths are resolved exactly as written; a project whose group `path`
differs from the folder on disk only in letter case works on macOS but not on a
case-sensitive filesystem.

Xcode 16 "synchronized folders" (`PBXFileSystemSynchronizedRootGroup`
referenced from a target's `fileSystemSynchronizedGroups`) are read from disk:
every `*.swift` under the folder (recursive, sorted) is a source of the target
and every `*.xcassets` an asset catalog, minus the paths listed in the target's
`PBXFileSystemSynchronizedBuildFileExceptionSet.membershipExceptions`. A folder
missing on disk contributes nothing.

## Build settings

`target.settings(configuration?)` merges the project-level `buildSettings` of
the named `XCBuildConfiguration` with the target-level ones on top. The default
configuration is `Debug` when the target has one, else the configuration list's
`defaultConfigurationName`. Array-valued settings are space-joined.
`$(TARGET_NAME)`, `$(PRODUCT_NAME)`, `$(SRCROOT)` and `$(PROJECT_DIR)` (also in
`${...}` form) are expanded; every other `$(...)` reference, including
`$(inherited)` and modifiers such as `$(X:rfc1034identifier)`, is left as is.

## Not handled

- `.xcconfig` files referenced by `baseConfigurationReference` are not read, so
  settings defined only there are absent.
- Binary `Info.plist` files are skipped (only XML plists are read).
- `PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet` (Xcode 16
  per-build-phase exceptions) and `PBXBuildRule`s are ignored.
- Workspaces (`.xcworkspace`), referenced projects (`PBXReferenceProxy`) and
  `PBXAggregateTarget`/`PBXLegacyTarget` are not modelled; only
  `PBXNativeTarget`s appear in `targets`.