rork-xcode 0.10.0 → 0.12.0

package/README.md

@@ -100,7 +100,7 @@ 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.
+`getBuildSetting` resolves hierarchically the way Xcode does, reading the target's default configuration first and the project-level configuration below it. Writes go to every configuration of the target, so Debug and Release stay consistent.
 
 ```ts
 const app = project.findMainAppTarget("ios"); // "macos" | "tvos" | "watchos" | "visionos"
@@ -114,6 +114,13 @@ for (const target of project.nativeTargets()) {
 }
 ```
 
+`resolveBuildSetting` reads the same layers and expands the `$(NAME)` and `${NAME}` references in the value. Referenced settings resolve through the chain, `$(inherited)` continues from the next layer down, and `$(TARGET_NAME)` falls back to the target's name, so the template's `PRODUCT_NAME = "$(TARGET_NAME)"` resolves without any setup. References the document cannot answer (build-system paths like `$(BUILT_PRODUCTS_DIR)`) stay verbatim unless a caller-supplied lookup answers them, so nothing is invented.
+
+```ts
+app?.resolveBuildSetting("PRODUCT_NAME"); // "DemoApp", from PRODUCT_NAME = "$(TARGET_NAME)"
+app?.resolveBuildSetting("WIDGET_ID"); // "com.example.demo.widget", through PRODUCT_BUNDLE_IDENTIFIER
+```
+
 `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
@@ -273,6 +280,27 @@ const text = scheme.build();
 
 Underneath, the document is a plain tree of elements with ordered attributes and children, reachable through `scheme.root` and `scheme.elements(name)`, so anything the typed surface does not cover stays one property away. `parseXcscheme` and `buildXcscheme` remain available for working with the tree directly. Attribute order is preserved and meaningful, 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.
 
+## Workspaces
+
+A `.xcworkspace` directory carries a `contents.xcworkspacedata` file listing the projects and folders the workspace shows, in the same XML dialect scheme files use, with the same round-trip contract. An Xcode-written file rebuilds byte for byte, any other input reaches the canonical layout in one build, and malformed input fails with a typed error carrying line and column.
+
+`Xcworkspace` is the model. Its flagship read resolves which projects the workspace references, so tooling stops globbing directory trees and asks the file that already knows:
+
+```ts
+import { Xcworkspace } from "rork-xcode";
+
+const workspace = Xcworkspace.parse(xcworkspacedataText);
+
+workspace.projectFilePaths(); // ["DemoApp.xcodeproj", "Pods/Pods.xcodeproj"]
+
+workspace.addFileRef("group:Vendor/Vendor.xcodeproj");
+const text = workspace.build();
+```
+
+Group locations compose through their enclosing groups, container locations anchor at the workspace's directory, and absolute locations pass through. The resolution is textual, because the library never touches the filesystem, so locations only a running Xcode can resolve (`self` and `developer`) stay out of the list. `Xcworkspace.create` produces the document Xcode writes for a new workspace, file references come back as typed views through `fileRefs()`, and `parseXcworkspace` and `buildXcworkspace` remain available for working with the tree directly.
+
+The other files inside a `.xcworkspace`, such as `WorkspaceSettings.xcsettings` and `IDEWorkspaceChecks.plist` under `xcshareddata`, are standard property lists rather than this dialect. [`rork-plist`](https://www.npmjs.com/package/rork-plist) parses and writes them with the same round-trip discipline, and the two libraries compose.
+
 ## Xcconfig files
 
 Build settings do not only live in the pbxproj. Projects push them into `.xcconfig` files referenced through `baseConfigurationReference`, and the xcconfig module reads and writes that format with the fidelity the rest of the library promises. The format is hand-authored with no canonical layout, so the contract here is losslessness. Parsing and building an untouched file reproduces it byte for byte, including comments, blank lines, column alignment, and line endings. Malformed lines fail loudly with a typed error carrying line and column rather than being dropped, so a file the parser accepts is a file it fully understood.
@@ -314,6 +342,24 @@ project.registerXcconfig(reference, Xcconfig.parse(text));
 app.getBuildSetting("SDKROOT"); // now sees values the xcconfig defines
 ```
 
+## Build-setting references
+
+Values reference other build settings as `$(NAME)` and `${NAME}`, in the pbxproj, in xcconfig files, and in Info.plist templates. The syntax is Xcode's own, down to the `:` operators, and Xcode's app templates write values in exactly this shape, for example `PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.$(PRODUCT_NAME:rfc1034identifier)`. `expandBuildSettingReferences` evaluates the syntax through a caller-supplied lookup, so the same code serves all three formats. Substituted text expands recursively, names may themselves contain references (`$(SETTING_$(VARIANT))`), cycles stay finite, and a reference the lookup cannot answer stays verbatim, so partial resolution loses no information.
+
+```ts
+import { expandBuildSettingReferences } from "rork-xcode";
+
+// A value as found in a project file. The references and their operators
+// are part of the document, so the expander takes them from the text
+// rather than from options.
+const found = "com.example.$(PRODUCT_NAME:rfc1034identifier)";
+
+expandBuildSettingReferences(found, (name) => (name === "PRODUCT_NAME" ? "My App" : undefined));
+// "com.example.My-App"
+```
+
+The `:` operators are honored for `lower`, `upper`, `rfc1034identifier` (the mapping into RFC 1034 host-name characters that bundle identifiers need), `c99extidentifier`, and `default=`. A reference carrying any other operator stays verbatim rather than expanding to a wrongly transformed value. The model composes the expander with settings resolution as `target.resolveBuildSetting(key)`, described under [Targets and build settings](#targets-and-build-settings).
+
 ## 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.
@@ -331,6 +377,17 @@ app.getBuildSetting("SDKROOT"); // now sees values the xcconfig defines
 | build     | app, Xcode 16           | **37.5 µs**  | 113.6 µs (3.0×)  | 71.3 µs (1.9×)   |
 | build     | generated app           | **0.98 ms**  | 85.98 ms (87.7×) | 1.20 ms (1.2×)   |
 
+The XML dialect files measure against `@bacons/xcode`, the one other npm package that parses and writes them (the `xcode` package has no scheme or workspace support):
+
+| Operation | Document                    | `rork-xcode` | `@bacons/xcode` |
+| --------- | --------------------------- | ------------ | --------------- |
+| parse     | app scheme (3.3 KiB)        | **28.1 µs**  | 108.7 µs (3.9×) |
+| parse     | actions scheme (5.8 KiB)    | **46.7 µs**  | 185.7 µs (4.0×) |
+| parse     | grouped workspace (0.7 KiB) | **4.7 µs**   | 20.5 µs (4.3×)  |
+| build     | app scheme                  | **7.1 µs**   | 8.0 µs (1.1×)   |
+| build     | actions scheme              | **11.9 µs**  | 13.8 µs (1.2×)  |
+| build     | grouped workspace           | **2.2 µs**   | 3.0 µs (1.4×)   |
+
 Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0.0-alpha.33 and `xcode` 3.0.1. Multipliers are relative to `rork-xcode` on the same row; the ordering also holds on Bun. Reproduce with `pnpm bench:compare`, which interleaves the libraries in round-robin batches and reports the median, after verifying that every library round-trips every fixture.
 
 ### Key performance features
@@ -339,13 +396,14 @@ Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0
 - **Comments skip in bulk.** Reference comments are a sizable share of a canonical document's bytes, so comment bodies are jumped with `indexOf` instead of being scanned per character.
 - **Linear comment derivation.** Building the `/* … */` annotations uses reverse indexes over the object graph (build file → phase, configuration list → owner), so serialization stays linear on projects with thousands of objects.
 - **Memoized rendering.** Quoting decisions for the repeated key vocabulary and rendered uuid references are cached per document, halving the quote scans on reference-heavy sections.
+- **Single-scan XML writing.** Attribute values pass one character-class test, and the near-universal value with nothing to escape returns as-is. The same machinery validates what XML cannot carry, and error paths are resolved only when a build actually fails, so correctness checks cost nothing on the happy path.
 
 ## Verification
 
 - 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, and 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, scheme, and xcconfig on the machine, verifies each one parses and reaches a byte-stable fixed point (byte-exact losslessness for xcconfig, which has no canonical layout), exercises the object model against every project, and cross-validates a sample against plutil's own reading.
+- A corpus sweep (`pnpm corpus`) walks every Xcode project, scheme, workspace, and xcconfig on the machine, verifies each one parses and reaches a byte-stable fixed point (byte-exact losslessness for xcconfig, which has no canonical layout), 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

package/dist/index.d.ts

@@ -82,13 +82,14 @@ declare function buildPbxproj(root: PbxprojObject): string;
  * @module
  */
 /**
- * Location of a parse failure inside the source text.
+ * Location of a parse failure inside the source text, shared by every
+ * parse error the library throws.
  *
  * Offsets count UTF-16 code units from the start of the string (the same
  * units `String.prototype.slice` uses), so editors and log tooling can jump
  * straight to the failure.
  */
-interface PbxprojErrorPosition {
+interface TextPosition {
   /** Zero-based character offset into the source string. */
   offset: number;
   /** One-based line number. */
@@ -96,6 +97,12 @@ interface PbxprojErrorPosition {
   /** One-based column number, in characters from the start of the line. */
   column: number;
 }
+/**
+ * The name {@link TextPosition} carried before the scheme, workspace, and
+ * xcconfig parsers shared it. Kept as an alias so existing annotations
+ * keep compiling.
+ */
+type PbxprojErrorPosition = TextPosition;
 /**
  * Thrown when the source text is not a well-formed OpenStep-style property
  * list (the format of `project.pbxproj` files).
@@ -106,7 +113,7 @@ interface PbxprojErrorPosition {
  */
 declare class PbxprojParseError extends Error {
   /** Where in the source text parsing failed. */
-  readonly position: PbxprojErrorPosition;
+  readonly position: TextPosition;
   /**
    * @param message Failure description without location. The location is
    *   appended automatically.
@@ -125,7 +132,26 @@ declare class PbxprojParseError extends Error {
  */
 declare class XcschemeParseError extends Error {
   /** Where in the source text parsing failed. */
-  readonly position: PbxprojErrorPosition;
+  readonly position: TextPosition;
+  /**
+   * @param message Failure description without location. The location is
+   *   appended automatically.
+   * @param source Full source text, used to compute the position.
+   * @param offset Character offset of the failure inside `source`.
+   */
+  constructor(message: string, source: string, offset: number);
+}
+/**
+ * Thrown when the source text is not a well-formed workspace data file
+ * (the XML dialect of `contents.xcworkspacedata` files).
+ *
+ * The message always embeds the line and column of the failure, and the
+ * same information is available in structured form on {@link position}
+ * for programmatic use.
+ */
+declare class XcworkspaceParseError extends Error {
+  /** Where in the source text parsing failed. */
+  readonly position: TextPosition;
   /**
    * @param message Failure description without location. The location is
    *   appended automatically.
@@ -144,7 +170,7 @@ declare class XcschemeParseError extends Error {
  */
 declare class XcconfigParseError extends Error {
   /** Where in the source text parsing failed. */
-  readonly position: PbxprojErrorPosition;
+  readonly position: TextPosition;
   /**
    * @param message Failure description without location. The location is
    *   appended automatically.
@@ -170,6 +196,23 @@ declare class XcschemeBuildError extends Error {
    */
   constructor(message: string, path: string);
 }
+/**
+ * Thrown when a workspace element cannot be written as XML.
+ *
+ * Raised for element and attribute names that are not valid XML names and
+ * for attribute values carrying control characters XML 1.0 cannot encode.
+ * The {@link path} pinpoints the offending element inside the tree.
+ */
+declare class XcworkspaceBuildError extends Error {
+  /** Path to the offending element from the root, e.g. `Workspace.FileRef[0]`. */
+  readonly path: string;
+  /**
+   * @param message Failure description without location. The element path
+   *   is appended automatically.
+   * @param path Path to the offending element from the root.
+   */
+  constructor(message: string, path: string);
+}
 /**
  * Thrown by the object model when an operation cannot proceed, because the
  * document lacks the structure the operation needs (no objects dictionary,
@@ -207,6 +250,73 @@ declare class PbxprojBuildError extends Error {
   constructor(message: string, path: string);
 }
 //#endregion
+//#region src/expansion.d.ts
+/**
+ * Expansion of `$(NAME)` and `${NAME}` build-setting references.
+ *
+ * Values in the pbxproj, in xcconfig files, and in Info.plist templates
+ * reference other build settings, and every consumer that needs the
+ * resolved string ends up re-implementing the substitution informally.
+ * The expander here is a pure function over a caller-supplied lookup, so
+ * the same code serves all three formats. The model composes it with
+ * settings resolution in `Target.resolveBuildSetting`.
+ *
+ * @module
+ */
+/**
+ * The value a reference expands to, or `undefined` to leave the
+ * reference in place. Returning the empty string expands to nothing,
+ * which is how Xcode itself treats settings that exist but are empty.
+ */
+type BuildSettingLookup = (name: string) => string | undefined;
+interface ExpandBuildSettingOptions {
+  /**
+   * Whether lookup answers are expanded again, which is the default and
+   * suits lookups reading raw stored values. A lookup that resolves
+   * references itself, like the model's layered resolution, turns this
+   * off so text it deliberately left verbatim is not reinterpreted in
+   * the outer value's context.
+   */
+  expandLookupValues?: boolean;
+}
+/**
+ * Expands every `$(NAME)` and `${NAME}` reference in a value through the
+ * lookup. Substituted text is expanded again, so references are followed
+ * through chains of values, and reference names may themselves contain
+ * references (`$(SETTING_$(VARIANT))`), which expand innermost first.
+ *
+ * A lookup answer of `undefined` leaves the reference in the output
+ * verbatim, so partial resolution loses no information. A reference
+ * whose expansion would recurse into itself also stays verbatim, which
+ * keeps cyclic definitions finite. Xcode's `:` operators are honored for
+ * the forms below, and a reference carrying any other operator stays
+ * verbatim rather than expanding to a wrongly transformed value.
+ *
+ * The supported operators are `lower` and `upper` for case mapping,
+ * `rfc1034identifier` and `c99extidentifier` for the identifier
+ * mappings bundle identifiers and product module names use, and
+ * `default=value` for substituting a fallback when the setting resolves
+ * empty or is not known to the lookup.
+ */
+declare function expandBuildSettingReferences(value: string, lookup: BuildSettingLookup, options?: ExpandBuildSettingOptions): string;
+/**
+ * The transforming operators the expander supports, keyed by the name
+ * they are written with. `default=` is not listed because it carries an
+ * argument and substitutes rather than transforms, so the reference
+ * expansion handles it structurally.
+ */
+declare const OPERATOR_TRANSFORMS: {
+  c99extidentifier: (value: string) => string;
+  lower: (value: string) => string;
+  rfc1034identifier: (value: string) => string;
+  upper: (value: string) => string;
+};
+/**
+ * A transforming operator name honored in `$(NAME:operator)` references,
+ * alongside the structural `default=`.
+ */
+type BuildSettingOperator = keyof typeof OPERATOR_TRANSFORMS;
+//#endregion
 //#region src/model/isa.d.ts
 /**
  * Names and well-known values of the pbxproj object vocabulary.
@@ -593,6 +703,16 @@ interface BuildStyleProperties extends PbxprojObject {
 }
 //#endregion
 //#region src/model/target.d.ts
+interface ResolveBuildSettingOptions {
+  /**
+   * Answers references the document itself cannot, for example
+   * `$(BUILT_PRODUCTS_DIR)` when the caller knows the build layout. The
+   * lookup is consulted after the setting layers and before the built-in
+   * `$(TARGET_NAME)` fallback, and a reference it leaves unanswered
+   * stays verbatim in the result.
+   */
+  lookup?: BuildSettingLookup;
+}
 /**
  * The behavior every target kind shares. A target of any kind carries
  * build configurations and settings, build phases, and dependencies, and
@@ -637,6 +757,22 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    * reads as `undefined`.
    */
   getBuildSetting(key: string): string | undefined;
+  /**
+   * Reads a build setting like {@link getBuildSetting} and expands the
+   * `$(NAME)` and `${NAME}` references in it. Referenced settings resolve
+   * through the same layering, `$(inherited)` and a setting referencing
+   * itself continue from the next layer down the way Xcode composes
+   * values, and `$(TARGET_NAME)` falls back to the target's name, so the
+   * common `PRODUCT_NAME = "$(TARGET_NAME)"` resolves without any caller
+   * setup.
+   *
+   * References the model cannot resolve (build-system paths like
+   * `$(BUILT_PRODUCTS_DIR)`, environment values) stay in the result
+   * verbatim unless the caller's lookup answers them, so no information
+   * is invented. See {@link expandBuildSettingReferences} for the
+   * operator forms honored during expansion.
+   */
+  resolveBuildSetting(key: string, options?: ResolveBuildSettingOptions): string | undefined;
   /**
    * Writes a build setting on every configuration of the target, so Debug
    * and Release stay consistent.
@@ -2033,61 +2169,100 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
  */
 declare function parsePbxproj(text: string): PbxprojValue;
 //#endregion
-//#region src/scheme/types.d.ts
+//#region src/xml/types.d.ts
 /**
- * The node model of a scheme document.
+ * The node model of Xcode's XML dialect, shared by scheme files
+ * (`.xcscheme`) and workspace data files (`contents.xcworkspacedata`).
  *
- * A parsed `.xcscheme` is a tree of plain objects. Elements carry ordered
+ * A parsed document is a tree of plain objects. Elements carry ordered
  * attributes and child nodes, and comments survive as their own nodes.
  * All state lives in this tree. There is no wrapper to keep in sync, so
- * callers mutate nodes directly and serialize whatever the tree currently
- * says.
+ * callers mutate nodes directly and serialize whatever the tree
+ * currently says.
  *
  * @module
  */
 /**
- * An XML element of a scheme document.
+ * An XML element of a document.
  *
  * Attribute order is preserved and meaningful. The writer emits
  * attributes in insertion order, which is how Xcode-written files
  * round-trip byte-identically. Assigning an existing key keeps its
  * position, and adding a new key appends it.
  */
-interface XcschemeElement {
-  /** Tag name, for example `Scheme` or `BuildableReference`. */
+interface XmlElement {
+  /** Tag name, for example `Scheme` or `FileRef`. */
   name: string;
   /** Attribute values by name, in document order. */
   attributes: Record<string, string>;
   /** Child elements and comments, in document order. */
-  children: XcschemeNode[];
+  children: XmlNode[];
 }
 /**
- * A comment inside a scheme document. Xcode never writes comments, but
- * hand-edited and tool-generated schemes can carry them, and dropping
- * them would make round-trips lossy.
+ * A comment inside a document. Xcode never writes comments, but
+ * hand-edited and tool-generated files can carry them, and dropping them
+ * would make round-trips lossy.
  */
-interface XcschemeComment {
+interface XmlComment {
   /** The comment text between `<!--` and `-->`, verbatim. */
   comment: string;
 }
+/**
+ * Any node an element can contain.
+ */
+type XmlNode = XmlElement | XmlComment;
+/**
+ * A parsed document, made of its root element plus any comments sitting
+ * outside it. Xcode writes only the root, so the comment lists are
+ * almost always empty, but files that carry them round-trip without
+ * loss.
+ */
+interface XmlDocument {
+  /** Comments before the root element. */
+  leading: XmlComment[];
+  /** The root element. */
+  root: XmlElement;
+  /** Comments after the root element. */
+  trailing: XmlComment[];
+}
+/**
+ * Whether a node is an element rather than a comment.
+ */
+declare function isXmlElement(node: XmlNode): node is XmlElement;
+/**
+ * Collects elements of the given name anywhere under a root, in document
+ * order, root included. Passing no name collects every element. Scheme
+ * and workspace models both build their typed views over this query.
+ */
+declare function xmlElements(root: XmlElement, name?: string): XmlElement[];
+//#endregion
+//#region src/scheme/types.d.ts
+/**
+ * An XML element of a scheme document.
+ *
+ * Attribute order is preserved and meaningful. The writer emits
+ * attributes in insertion order, which is how Xcode-written files
+ * round-trip byte-identically. Assigning an existing key keeps its
+ * position, and adding a new key appends it.
+ */
+type XcschemeElement = XmlElement;
+/**
+ * A comment inside a scheme document. Xcode never writes comments, but
+ * hand-edited and tool-generated schemes can carry them, and dropping
+ * them would make round-trips lossy.
+ */
+type XcschemeComment = XmlComment;
 /**
  * Any node a scheme element can contain.
  */
-type XcschemeNode = XcschemeElement | XcschemeComment;
+type XcschemeNode = XmlNode;
 /**
  * A parsed scheme file, made of its root element plus any comments
  * sitting outside it. Xcode writes only the root, so the comment lists
  * are almost always empty, but files that carry them round-trip without
  * loss.
  */
-interface XcschemeDocument {
-  /** Comments before the root element. */
-  leading: XcschemeComment[];
-  /** The `Scheme` element. */
-  root: XcschemeElement;
-  /** Comments after the root element. */
-  trailing: XcschemeComment[];
-}
+type XcschemeDocument = XmlDocument;
 /**
  * Whether a node is an element rather than a comment.
  */
@@ -2095,7 +2270,8 @@ declare function isXcschemeElement(node: XcschemeNode): node is XcschemeElement;
 //#endregion
 //#region src/scheme/build.d.ts
 /**
- * Serializes a scheme document to the text of a `.xcscheme` file.
+ * Serializes a scheme document to the text of a `.xcscheme` file in
+ * Xcode's canonical layout.
  *
  * @throws XcschemeBuildError for element or attribute names that are not
  *   XML names and for attribute values carrying unencodable control
@@ -2280,6 +2456,147 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  */
 declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
 //#endregion
+//#region src/workspace/build.d.ts
+/**
+ * Serializes a workspace document to the text of a
+ * `contents.xcworkspacedata` file in Xcode's canonical layout.
+ *
+ * @throws XcworkspaceBuildError for element or attribute names that are
+ *   not XML names and for attribute values carrying unencodable control
+ *   characters, with the path of the offending node.
+ */
+declare function buildXcworkspace(document: XmlDocument): string;
+//#endregion
+//#region src/workspace/model.d.ts
+/**
+ * A workspace location string split at its kind prefix, so
+ * `group:Pods/Pods.xcodeproj` reads as the kind `group` and the path
+ * `Pods/Pods.xcodeproj`. A location without a kind prefix reads as
+ * `group`, which is how Xcode treats a bare path.
+ */
+interface WorkspaceLocation {
+  /** The anchor the path is relative to, for example `group`. */
+  kind: string;
+  /** The path after the kind prefix. */
+  path: string;
+}
+/**
+ * Splits a location attribute into its kind and path. Xcode writes the
+ * kinds `group` (relative to the enclosing group), `container` (relative
+ * to the directory containing the `.xcworkspace`), `absolute`, `self`
+ * (the containing `.xcodeproj` itself), and `developer` (inside the
+ * developer directory).
+ */
+declare function parseWorkspaceLocation(location: string): WorkspaceLocation;
+/**
+ * A `FileRef` element with property-style attribute access. File
+ * references are the elements workspace edits touch, since each one
+ * names a project or folder the workspace shows. The view reads and
+ * writes the element's attributes directly, so it never goes stale and
+ * needs no separate save step.
+ */
+declare class WorkspaceFileRef {
+  /** The underlying element inside the document tree. */
+  readonly element: XmlElement;
+  constructor(element: XmlElement);
+  /**
+   * The reference's location attribute, when present, for example
+   * `group:Pods/Pods.xcodeproj`.
+   */
+  get location(): string | undefined;
+  set location(value: string);
+}
+interface CreateXcworkspaceOptions {
+  /**
+   * The location of each file reference the workspace lists, in order,
+   * for example `group:DemoApp.xcodeproj`. An omitted list creates an
+   * empty workspace to add references to.
+   */
+  locations?: string[];
+}
+/**
+ * A workspace document with typed access to the elements editing flows
+ * touch.
+ *
+ * The model is a thin layer over the node tree. All state lives in the
+ * document itself, and {@link build} serializes whatever the tree
+ * currently says, so typed edits and direct tree edits compose freely.
+ *
+ * ```ts
+ * const workspace = Xcworkspace.parse(xcworkspacedataText);
+ * workspace.projectFilePaths(); // ["DemoApp.xcodeproj", "Pods/Pods.xcodeproj"]
+ * ```
+ */
+declare class Xcworkspace {
+  /** The underlying parsed document. */
+  readonly document: XmlDocument;
+  constructor(document: XmlDocument);
+  /**
+   * Parses the text of a `contents.xcworkspacedata` file into a
+   * workspace model.
+   *
+   * @throws XcworkspaceParseError when the text is not a well-formed
+   *   workspace document, with the line and column of the failure.
+   */
+  static parse(text: string): Xcworkspace;
+  /**
+   * Creates the workspace document Xcode writes, listing the given
+   * locations as file references.
+   */
+  static create(options?: CreateXcworkspaceOptions): Xcworkspace;
+  /**
+   * The document's `Workspace` element.
+   */
+  get root(): XmlElement;
+  /**
+   * Serializes the workspace to the text of a `contents.xcworkspacedata`
+   * file in Xcode's canonical layout.
+   */
+  build(): string;
+  /**
+   * Collects elements of the given name anywhere in the document, in
+   * document order. Passing no name collects every element.
+   */
+  elements(name?: string): XmlElement[];
+  /**
+   * The views of every file reference in the document, in document
+   * order, references nested inside groups included.
+   */
+  fileRefs(): WorkspaceFileRef[];
+  /**
+   * Appends a file reference to the workspace's top level and returns
+   * its view.
+   */
+  addFileRef(location: string): WorkspaceFileRef;
+  /**
+   * Removes a file reference from whichever element holds it. Returns
+   * whether the reference was found and removed.
+   */
+  removeFileRef(reference: WorkspaceFileRef): boolean;
+  /**
+   * The paths of every `.xcodeproj` the workspace references, in
+   * document order, resolved relative to the directory containing the
+   * `.xcworkspace`. Group locations compose through their enclosing
+   * groups, container locations anchor at the workspace's directory, and
+   * absolute locations pass through unchanged.
+   *
+   * The resolution is textual. The library never touches the
+   * filesystem, so locations that only the running Xcode can resolve
+   * (`self` and `developer`) are not listed.
+   */
+  projectFilePaths(): string[];
+}
+//#endregion
+//#region src/workspace/parse.d.ts
+/**
+ * Parses the text of a `contents.xcworkspacedata` file into its node
+ * tree.
+ *
+ * @throws XcworkspaceParseError when the text is not a well-formed
+ *   workspace document, with the line and column of the failure.
+ */
+declare function parseXcworkspace(text: string): XmlDocument;
+//#endregion
 //#region src/xcconfig/build.d.ts
 /**
  * Serializes a document back to `.xcconfig` text.
@@ -2296,4 +2613,4 @@ declare function buildXcconfig(document: XcconfigDocument): string;
  */
 declare function parseXcconfig(source: string): XcconfigDocument;
 //#endregion
-export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, Xcconfig, type XcconfigAssignment, type XcconfigBlank, type XcconfigComment, type XcconfigCondition, type XcconfigDocument, type XcconfigInclude, type XcconfigIncludeResolver, XcconfigParseError, type XcconfigSettingsOptions, type XcconfigStatement, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcconfig, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcconfig, parseXcscheme, xcschemeElements };
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettingLookup, type BuildSettingOperator, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, type CreateXcworkspaceOptions, ExceptionSet, type ExceptionSetProperties, type ExpandBuildSettingOptions, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, type ResolveBuildSettingOptions, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, type TextPosition, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, WorkspaceFileRef, type WorkspaceLocation, Xcconfig, type XcconfigAssignment, type XcconfigBlank, type XcconfigComment, type XcconfigCondition, type XcconfigDocument, type XcconfigInclude, type XcconfigIncludeResolver, XcconfigParseError, type XcconfigSettingsOptions, type XcconfigStatement, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, Xcworkspace, XcworkspaceBuildError, XcworkspaceParseError, type XmlComment, type XmlDocument, type XmlElement, type XmlNode, buildPbxproj, buildXcconfig, buildXcscheme, buildXcworkspace, createXcscheme, expandBuildSettingReferences, generateObjectId, isXcschemeElement, isXmlElement, parseApplePlatform, parsePbxproj, parseWorkspaceLocation, parseXcconfig, parseXcscheme, parseXcworkspace, xcschemeElements, xmlElements };