rork-xcode 0.9.0 → 0.10.0

package/README.md

@@ -206,6 +206,17 @@ if (widget) project.removeTarget(widget);
 project.referrersOf(app.id); // every object referencing an id, for custom teardowns
 ```
 
+### Renaming
+
+`renameTarget` renames a target and every place the document knows it by name. That covers the target's `name` and `productName`, its product file reference, the `remoteInfo` of container proxies pointing at it, `TEST_TARGET_NAME` values naming it, and the path segments of `TEST_HOST` and `BUNDLE_LOADER` that name the target or its product. Names match whole, so renaming `DemoApp` leaves `DemoAppTests` alone, and a `PRODUCT_NAME` of `$(TARGET_NAME)` follows by itself. On-disk renames (source folders, entitlements files) and the group paths pointing at those folders stay with the caller.
+
+```ts
+const app = project.findMainAppTarget("ios");
+if (app) project.renameTarget(app, "RenamedApp");
+```
+
+Scheme files live next to the project rather than inside it, so the scheme model carries the counterpart (see [Schemes](#schemes)).
+
 ### 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:
@@ -235,25 +246,21 @@ for (const [id, object] of project.objects()) {
 
 `.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 the scheme module covers 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.
 
-`Xcscheme` is the model. Buildable references are the elements editing flows touch, and they come back as typed views:
+`Xcscheme` is the model. Renames are one call per move. `renameTarget` is the scheme-file side of the project model's `renameTarget` and touches only the named target's references, and `renameContainer` follows a rename of the `.xcodeproj` directory itself. Both return whether anything changed, so callers can skip rewriting untouched files:
 
 ```ts
 import { Xcscheme } from "rork-xcode";
 
 const scheme = Xcscheme.parse(xcschemeText);
 
-// Rename the app while keeping each product's own shape, so a testable
-// like DemoAppTests.xctest stays a test bundle.
-for (const reference of scheme.buildableReferences()) {
-  const { blueprintName, buildableName } = reference;
-  if (blueprintName) reference.blueprintName = blueprintName.replace("DemoApp", "RenamedApp");
-  if (buildableName) reference.buildableName = buildableName.replace("DemoApp", "RenamedApp");
-  reference.referencedContainer = "container:RenamedApp.xcodeproj";
-}
+scheme.renameTarget("DemoApp", "RenamedApp"); // DemoAppTests stays untouched
+scheme.renameContainer("DemoApp", "RenamedApp"); // container:RenamedApp.xcodeproj
 
 const text = scheme.build();
 ```
 
+For anything else, buildable references come back as typed views through `scheme.buildableReferences()`, with property access to the blueprint name, buildable name, container, and identifier.
+
 `Xcscheme.create` 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
@@ -268,7 +275,7 @@ Underneath, the document is a plain tree of elements with ordered attributes and
 
 ## 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 — comments, blank lines, column alignment, and line endings included. 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.
+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.
 
 `Xcconfig` is the model. Reads follow the file top to bottom the way Xcode does, and writes edit single lines while leaving every other byte alone:
 
@@ -300,7 +307,7 @@ const settings = config.settings({
 });
 ```
 
-Registering a file on the project makes `getBuildSetting` resolve through it in Xcode's order — target settings, the target's xcconfig, project settings, the project's xcconfig:
+Registering a file on the project makes `getBuildSetting` resolve through it in Xcode's order of target settings, then the target's xcconfig, then project settings, then the project's xcconfig:
 
 ```ts
 project.registerXcconfig(reference, Xcconfig.parse(text));
@@ -336,7 +343,7 @@ Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0
 ## 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; documents from other tool generations must normalize to a byte-stable fixed point with unchanged values.
+- 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.
 - CI runs the full gate on Linux and macOS, and executes the built artifact on the oldest supported Node to enforce the `engines` floor.

package/dist/index.d.ts

@@ -10,33 +10,34 @@
  * - `( item, item, ... )` parses to a {@link PbxprojArray}.
  * - `<48656c6c6f>` data runs parse to `Uint8Array`.
  * - Unquoted integers and decimals (`46`, `3.14`, `-12`) parse to `number`
- *   under one print-back rule: the literal converts exactly when the number
- *   formats back to the identical text.
+ *   under one print-back rule, where the literal converts exactly when the
+ *   number formats back to the identical text.
  * - Everything else (quoted text, identifiers, uuids, paths) parses to
  *   `string`.
  *
- * The print-back rule is what keeps round-trips faithful: any literal the
+ * The print-back rule is what keeps round-trips faithful. Any literal the
  * conversion would reshape stays a string, so serializing never changes a
  * scalar's bytes. Leading-zero runs like `0755` would corrupt file modes,
- * trailing-zero decimals like `5.0` would drop the zero build settings are
- * written with, bare-dot decimals like `.5` would grow a leading zero, and
+ * trailing-zero decimals like `5.0` would drop the zero that build
+ * settings are written with, bare-dot decimals like `.5` would grow a
+ * leading zero, and
  * digit runs beyond `Number.MAX_SAFE_INTEGER` would lose precision (a
- * 24-character identifier can be all digits); all of these therefore parse
- * as strings.
+ * 24-character identifier can be all digits), so all of these parse as
+ * strings.
  *
  * @module
  */
 /**
  * A value representable in a `project.pbxproj` document.
  *
- * Notably absent are booleans and null: the format has no notation for
+ * Notably absent are booleans and null. The format has no notation for
  * either, and Xcode models flags as the strings `"YES"` and `"NO"`.
  */
 type PbxprojValue = string | number | Uint8Array | PbxprojArray | PbxprojObject;
 /**
  * A `( ... )` list: an ordered array of values.
  *
- * This is a plain JavaScript array; the interface exists only to give the
+ * This is a plain JavaScript array. The interface exists only to give the
  * recursive {@link PbxprojValue} type a name.
  */
 interface PbxprojArray extends Array<PbxprojValue> {}
@@ -55,18 +56,18 @@ interface PbxprojObject {
 /**
  * Serializes a project document to `project.pbxproj` text.
  *
- * The input is the same shape {@link parsePbxproj} produces; see the module
- * documentation of `types.ts` for the value model. Output is stable: two
+ * The input is the same shape {@link parsePbxproj} produces. See the module
+ * documentation of `types.ts` for the value model. Output is stable, so two
  * calls with semantically equal documents produce identical text, and the
  * layout matches what Xcode itself writes so diffs stay minimal.
  *
  * @param root The document root. Real project documents carry `objects`,
  *   `rootObject`, and the version fields, but any dictionary serializes.
  * @returns The document text, terminated by a newline.
- * @throws PbxprojBuildError when a value has no pbxproj representation:
- *   `null`, `undefined`, booleans, bigints, functions, symbols, class
- *   instances, or non-finite numbers. The error names the path of the
- *   offending value.
+ * @throws PbxprojBuildError when a value has no pbxproj representation,
+ *   meaning `null`, `undefined`, booleans, bigints, functions, symbols,
+ *   class instances, or non-finite numbers. The error names the path of
+ *   the offending value.
  */
 declare function buildPbxproj(root: PbxprojObject): string;
 //#endregion
@@ -107,7 +108,7 @@ declare class PbxprojParseError extends Error {
   /** Where in the source text parsing failed. */
   readonly position: PbxprojErrorPosition;
   /**
-   * @param message Failure description without location; the location is
+   * @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`.
@@ -126,7 +127,7 @@ declare class XcschemeParseError extends Error {
   /** Where in the source text parsing failed. */
   readonly position: PbxprojErrorPosition;
   /**
-   * @param message Failure description without location; the location is
+   * @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`.
@@ -145,7 +146,7 @@ declare class XcconfigParseError extends Error {
   /** Where in the source text parsing failed. */
   readonly position: PbxprojErrorPosition;
   /**
-   * @param message Failure description without location; the location is
+   * @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`.
@@ -163,14 +164,14 @@ declare class XcschemeBuildError extends Error {
   /** Path to the offending element from the root, e.g. `Scheme.BuildAction[0]`. */
   readonly path: string;
   /**
-   * @param message Failure description without location; the element path
+   * @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: the
+ * Thrown by the object model when an operation cannot proceed, because the
  * document lacks the structure the operation needs (no objects dictionary,
  * no root project object), a view's object was removed from the document,
  * or a creation request names a product type the model cannot scaffold.
@@ -199,7 +200,7 @@ declare class PbxprojBuildError extends Error {
   /** Path to the offending value from the root, e.g. `$.objects.13B07F86.name`. */
   readonly path: string;
   /**
-   * @param message Failure description without location; the value path is
+   * @param message Failure description without location. The value path is
    *   appended automatically.
    * @param path Path to the offending value from the root, `$`.
    */
@@ -210,15 +211,15 @@ declare class PbxprojBuildError extends Error {
 /**
  * Names and well-known values of the pbxproj object vocabulary.
  *
- * Everything here mirrors strings Xcode itself writes; nothing is invented.
- * Centralizing them keeps the object model free of string literals and
- * gives call sites one place to import from.
+ * Everything here mirrors strings Xcode itself writes, and nothing is
+ * invented. Centralizing them keeps the object model free of string
+ * literals and gives call sites one place to import from.
  *
  * @module
  */
 /**
  * The `isa` names the object model works with. The parser and serializer
- * accept any isa; this list only covers the kinds the model creates or
+ * accept any isa, and this list only covers the kinds the model creates or
  * gives typed access to.
  */
 declare const Isa: {
@@ -629,11 +630,11 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    *
    * Configurations based on `.xcconfig` files take part once the files
    * are registered through {@link XcodeProject.registerXcconfig}, in
-   * Xcode's order: target settings, the target's xcconfig, project
-   * settings, the project's xcconfig.
+   * Xcode's order of target settings, then the target's xcconfig, then
+   * project settings, then the project's xcconfig.
    *
-   * Only string values are returned; a list- or number-valued setting reads
-   * as `undefined`.
+   * Only string values are returned, so a list- or number-valued setting
+   * reads as `undefined`.
    */
   getBuildSetting(key: string): string | undefined;
   /**
@@ -879,7 +880,7 @@ declare class Group<Properties extends GroupProperties = GroupProperties> extend
    * it to the group's children.
    *
    * The reference's `lastKnownFileType` derives from the file extension
-   * when it is a known kind; otherwise the reference carries no type and
+   * when it is a known kind. Otherwise the reference carries no type and
    * Xcode re-derives one on open.
    *
    * @param path File path relative to the group, for example
@@ -905,8 +906,8 @@ declare class VariantGroup extends Group {
 declare class BuildPhase<Properties extends BuildPhaseProperties = BuildPhaseProperties> extends XcodeObject<Properties> {
   /**
    * The phase's display name, when it carries an explicit one. Xcode names
-   * copy-files and shell-script phases; the standard phases derive their
-   * names from their isa.
+   * copy-files and shell-script phases, while the standard phases derive
+   * their names from their isa.
    */
   get name(): string | undefined;
   /**
@@ -934,7 +935,7 @@ declare class BuildPhase<Properties extends BuildPhaseProperties = BuildPhasePro
    * @param reference The file reference or package product the build file
    *   should point at.
    * @param options.referenceKey Which build-file field carries the
-   *   reference: `fileRef` for file references (the default) or
+   *   reference, either `fileRef` for file references (the default) or
    *   `productRef` for Swift package products.
    * @param options.settings Optional per-file settings, for example
    *   `{ ATTRIBUTES: ["RemoveHeadersOnCopy"] }`.
@@ -1029,7 +1030,7 @@ declare class BuildFile extends XcodeObject<BuildFileProperties> {
   /**
    * The view of the file reference the build file points at, when it
    * points at one. Build files for Swift package products carry a
-   * `productRef` instead; see {@link productDependency}.
+   * `productRef` instead, resolved through {@link productDependency}.
    */
   fileReference(): XcodeObject | undefined;
   /**
@@ -1055,12 +1056,12 @@ declare class SyncRootGroup extends XcodeObject<SyncRootGroupProperties> {
    *
    * Xcode keeps one exception set per target and folder, so when this
    * group already carries a set for the target, the file names merge into
-   * it instead of creating a second set; names already excluded are not
-   * duplicated.
+   * it instead of creating a second set, and names already excluded are
+   * not duplicated.
    *
    * The standard use is keeping a scaffolded `Info.plist` from being
-   * double-copied: the build already processes it through the target's
-   * `INFOPLIST_FILE` setting.
+   * double-copied, since the build already processes it through the
+   * target's `INFOPLIST_FILE` setting.
    *
    * @param target The target whose membership the exceptions restrict.
    * @param membershipExceptions File names inside the folder to exclude.
@@ -1540,7 +1541,7 @@ declare class RootProject extends XcodeObject<RootProjectProperties> {
   mainGroup(): Group | undefined;
   /**
    * The settings dictionary of the project-level default configuration.
-   * Targets inherit from these settings; see
+   * Targets inherit from these settings, as described on
    * {@link NativeTarget.getBuildSetting}.
    */
   defaultConfigurationSettings(): PbxprojObject | undefined;
@@ -1619,7 +1620,7 @@ declare class XcodeProject {
   static parse(text: string): XcodeProject;
   /**
    * Wraps an already parsed document in a model. The document is used in
-   * place, not copied; model mutations write into it.
+   * place rather than copied, so model mutations write into it.
    */
   static fromDocument(document: PbxprojObject): XcodeProject;
   /**
@@ -1630,7 +1631,7 @@ declare class XcodeProject {
   /**
    * The raw properties dictionary of an object.
    *
-   * @throws XcodeModelError when no object with the id exists; views use
+   * @throws XcodeModelError when no object with the id exists. Views use
    *   this accessor, so a view of a deleted object fails loudly instead of
    *   resurrecting the entry.
    */
@@ -1653,8 +1654,8 @@ declare class XcodeProject {
   objects(): IterableIterator<[string, XcodeObject]>;
   /**
    * Generates a deterministic 24-character id from a seed, avoiding every
-   * id the document currently contains. The id is not reserved; adding an
-   * object with it (see {@link add}) is what claims it.
+   * id the document currently contains. The id is not reserved, and only
+   * adding an object with it (see {@link add}) claims it.
    */
   generateId(seed: string): string;
   /**
@@ -1723,7 +1724,8 @@ declare class XcodeProject {
    * and Resources build phases, and registers it on the project.
    *
    * @throws XcodeModelError for product types the model cannot create a
-   *   product reference for; see {@link AddNativeTargetOptions.productType}.
+   *   product reference for, listed on
+   *   {@link AddNativeTargetOptions.productType}.
    */
   addNativeTarget(options: AddNativeTargetOptions): NativeTarget;
   /**
@@ -1733,7 +1735,7 @@ declare class XcodeProject {
   /**
    * Adds a remote Swift package reference and registers it on the project.
    * When the project already references the repository, the existing
-   * reference is returned unchanged, requirement included; adjust an
+   * reference is returned unchanged, requirement included. Adjust an
    * existing requirement through the reference's properties. Link products
    * to targets with {@link NativeTarget.addSwiftPackageProduct}.
    *
@@ -1786,7 +1788,7 @@ declare class XcodeProject {
    * list containing it, or a nested dictionary carrying it as a key or
    * string value.
    *
-   * The scan is linear over the document; removal flows call it once per
+   * The scan is linear over the document. Removal flows call it once per
    * removed object, which keeps teardown proportional to what is actually
    * removed.
    */
@@ -1798,7 +1800,7 @@ declare class XcodeProject {
    * (such as `TargetAttributes`) drop its entry.
    *
    * Removing an id the document does not contain is a no-op. This is the
-   * low-level removal; {@link removeTarget} composes it into a full
+   * low-level removal, and {@link removeTarget} composes it into a full
    * teardown.
    */
   removeObject(id: string): void;
@@ -1811,7 +1813,7 @@ declare class XcodeProject {
    * dependencies on others), its membership exception sets, and
    * synchronized folders no remaining target links.
    *
-   * On-disk sources are untouched; the removal is document-only, like
+   * On-disk sources are untouched. The removal is document-only, like
    * deleting a target in Xcode and keeping its folder.
    *
    * @throws XcodeModelError when the target belongs to another project,
@@ -1819,13 +1821,33 @@ declare class XcodeProject {
    *   objects that happen to share them.
    */
   removeTarget(target: Target): void;
+  /**
+   * Renames a target and every place the document knows it by name. That
+   * covers the target's `name` and `productName`, its product file
+   * reference (`OldName.app` becomes `NewName.app`, whatever the
+   * extension), the `remoteInfo` of container item proxies pointing at
+   * the target, `TEST_TARGET_NAME` settings naming it, and the path
+   * segments of `TEST_HOST` and `BUNDLE_LOADER` settings that name the
+   * target or its product. A `PRODUCT_NAME` of the target's own
+   * configurations is rewritten only when it spells the old name
+   * literally. The usual `$(TARGET_NAME)` follows by itself.
+   *
+   * Scheme files live outside the pbxproj, so buildable references are
+   * renamed separately through `Xcscheme.renameTarget`. On-disk renames
+   * (source folders, entitlements files) and the group paths pointing at
+   * those folders stay with the caller. Sibling targets such as
+   * `OldNameTests` are renamed with their own calls.
+   *
+   * @throws XcodeModelError when the target belongs to another project.
+   */
+  renameTarget(target: Target, newName: string): void;
   /**
    * Finds a file reference by its project-relative path, resolving each
    * reference's location through the group tree from the main group
    * (nested group `path` components join with `/`).
    *
    * Members of file-system-synchronized folders are not listed in the
-   * document and therefore cannot be found; check
+   * document and therefore cannot be found. Check
    * {@link NativeTarget.syncGroupPaths} for folder-level containment
    * instead.
    */
@@ -1987,8 +2009,8 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
    * nested dictionaries keyed by object id (such as the root project's
    * `TargetAttributes`) drop its entry.
    *
-   * This is the low-level removal; it does not cascade to objects that only
-   * made sense alongside this one. Higher-level operations like
+   * This is the low-level removal, so it does not cascade to objects that
+   * only made sense alongside this one. Higher-level operations like
    * {@link XcodeProject.removeTarget} compose it into full teardowns.
    */
   removeFromProject(): void;
@@ -2006,7 +2028,7 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
  * @param text Source text of the document.
  * @returns The document's root value. For real project files this is the
  *   root dictionary with `objects`, `rootObject`, and version fields.
- * @throws PbxprojParseError when the document is malformed; the error
+ * @throws PbxprojParseError when the document is malformed. The error
  *   carries the line and column of the failure.
  */
 declare function parsePbxproj(text: string): PbxprojValue;
@@ -2178,6 +2200,22 @@ declare class Xcscheme {
    * of these, so rename flows iterate this list.
    */
   buildableReferences(): BuildableReference[];
+  /**
+   * Renames every buildable reference pointing at a target. The blueprint
+   * name is matched whole, and the buildable name is matched by its stem,
+   * so `OldApp.app` becomes `NewApp.app` while `OldAppTests.xctest`, a
+   * different target's product, stays untouched. This is the scheme-file
+   * side of `XcodeProject.renameTarget`. Returns whether anything
+   * changed, so callers can skip rewriting untouched files.
+   */
+  renameTarget(oldName: string, newName: string): boolean;
+  /**
+   * Rewrites every buildable reference's container after the
+   * `.xcodeproj` directory itself is renamed, so `container:Old.xcodeproj`
+   * becomes `container:New.xcodeproj`. The project names are matched
+   * exactly. Returns whether anything changed.
+   */
+  renameContainer(oldProjectName: string, newProjectName: string): boolean;
 }
 /**
  * Options for {@link createXcscheme}.
@@ -2220,7 +2258,7 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  * Deterministic object identifiers for generated pbxproj objects.
  *
  * Xcode identifies every object with 24 hexadecimal characters. Generated
- * ids here are deterministic: the same seed always produces the same id, so
+ * ids here are deterministic. The same seed always produces the same id, so
  * programmatic edits are reproducible and diffs stay minimal across runs.
  * The format is `XX` + the first 20 characters of `md5(seed)` + `XX`, which
  * is a valid identifier that remains recognizable as generated.

package/dist/index.js

@@ -52,8 +52,8 @@ function repoNameFromUrl(repoUrl) {
 * Builds the uuid-to-comment map for a parsed project document.
 *
 * Objects that should render without a comment (unnamed groups) map to the
-* empty string; uuids absent from the map are not references at all.
-* Derivation is linear over the object graph: reverse indexes are built in
+* empty string, and uuids absent from the map are not references at all.
+* Derivation is linear over the object graph. Reverse indexes are built in
 * one pass, and every object's comment is computed once and cached.
 */
 function createReferenceComments(root) {
@@ -100,9 +100,9 @@ function createReferenceComments(root) {
 	};
 	/**
 	* Comment for a `PBXFileSystemSynchronizedBuildFileExceptionSet`,
-	* matching current Xcode: `Exceptions for "clip" folder in "clip"
-	* target`. Falls back to the isa when the folder or target cannot be
-	* resolved (older documents and hand-edited graphs).
+	* matching current Xcode, for example `Exceptions for "clip" folder in
+	* "clip" target`. Falls back to the isa when the folder or target cannot
+	* be resolved (older documents and hand-edited graphs).
 	*/
 	const buildFileExceptionSetComment = (id, set) => {
 		const folder = exceptionSetFolderName(id);
@@ -114,9 +114,9 @@ function createReferenceComments(root) {
 	};
 	/**
 	* Comment for a `PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet`,
-	* matching current Xcode: `Exceptions for "Tophat" folder in "CopyFiles"
-	* phase from "Tophat" target`. Falls back to the isa when any of the
-	* three names cannot be resolved.
+	* matching current Xcode, for example `Exceptions for "Tophat" folder in
+	* "CopyFiles" phase from "Tophat" target`. Falls back to the isa when
+	* any of the three names cannot be resolved.
 	*/
 	const membershipExceptionSetComment = (id, set) => {
 		const folder = exceptionSetFolderName(id);
@@ -246,7 +246,7 @@ var PbxprojParseError = class extends Error {
 	/** Where in the source text parsing failed. */
 	position;
 	/**
-	* @param message Failure description without location; the location is
+	* @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`.
@@ -270,7 +270,7 @@ var XcschemeParseError = class extends Error {
 	/** Where in the source text parsing failed. */
 	position;
 	/**
-	* @param message Failure description without location; the location is
+	* @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`.
@@ -294,7 +294,7 @@ var XcconfigParseError = class extends Error {
 	/** Where in the source text parsing failed. */
 	position;
 	/**
-	* @param message Failure description without location; the location is
+	* @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`.
@@ -317,7 +317,7 @@ var XcschemeBuildError = class extends Error {
 	/** Path to the offending element from the root, e.g. `Scheme.BuildAction[0]`. */
 	path;
 	/**
-	* @param message Failure description without location; the element path
+	* @param message Failure description without location. The element path
 	*   is appended automatically.
 	* @param path Path to the offending element from the root.
 	*/
@@ -328,7 +328,7 @@ var XcschemeBuildError = class extends Error {
 	}
 };
 /**
-* Thrown by the object model when an operation cannot proceed: the
+* Thrown by the object model when an operation cannot proceed, because the
 * document lacks the structure the operation needs (no objects dictionary,
 * no root project object), a view's object was removed from the document,
 * or a creation request names a product type the model cannot scaffold.
@@ -360,7 +360,7 @@ var PbxprojBuildError = class extends Error {
 	/** Path to the offending value from the root, e.g. `$.objects.13B07F86.name`. */
 	path;
 	/**
-	* @param message Failure description without location; the value path is
+	* @param message Failure description without location. The value path is
 	*   appended automatically.
 	* @param path Path to the offending value from the root, `$`.
 	*/
@@ -387,8 +387,8 @@ var PbxprojBuildError = class extends Error {
 */
 const UNQUOTED_SAFE_PATTERN = /^[A-Za-z0-9_$/:.]+$/u;
 /**
-* Whether the value can render without quotes: every character is in the
-* unquoted-safe alphabet and the string is not empty.
+* Whether the value can render without quotes, meaning every character is
+* in the unquoted-safe alphabet and the string is not empty.
 *
 * Quoting decisions scan every string a document carries, and many of those
 * strings are substring slices of the source text. The regex engine flattens
@@ -400,7 +400,7 @@ function isSafeUnquoted(value) {
 }
 /**
 * Whether the string contains characters that require escape sequences
-* inside a quoted string: control characters, `"`, `\`, or DEL.
+* inside a quoted string, meaning control characters, `"`, `\`, or DEL.
 */
 function needsEscaping(value) {
 	for (let i = 0; i < value.length; i++) {
@@ -410,8 +410,8 @@ function needsEscaping(value) {
 	return false;
 }
 /**
-* Escapes special characters for a quoted string: the named C-style escapes
-* plus `\Uxxxx` for remaining control characters.
+* Escapes special characters for a quoted string, using the named C-style
+* escapes plus `\Uxxxx` for remaining control characters.
 */
 function escapeString(value) {
 	let result = "";
@@ -463,7 +463,7 @@ function ensureQuotes(value) {
 	return `"${escapeString(value)}"`;
 }
 /**
-* Renders binary data as an uppercase hex run: `<DEADBEEF>`.
+* Renders binary data as an uppercase hex run, for example `<DEADBEEF>`.
 */
 function formatData(data) {
 	let hex = "";
@@ -485,7 +485,7 @@ function formatData(data) {
 * - reference comments (`13B07F86… /* AppDelegate.swift in Sources *​/`)
 *   derived from the object graph.
 *
-* Numbers render exactly as JavaScript formats them; the version-like
+* Numbers render exactly as JavaScript formats them. The version-like
 * settings Xcode writes with a trailing zero (`SWIFT_VERSION = 5.0`) arrive
 * from the parser as strings and round-trip verbatim, so no reformatting
 * heuristic is needed or applied.
@@ -541,25 +541,25 @@ function indentString(depth) {
 /**
 * Serialization state for one {@link buildPbxproj} call.
 *
-* The `write*` methods append directly to the output string; the `render*`
-* methods return fragments for the caller to place. Output accumulates by
-* appending, because engines represent growing strings as ropes: appends
-* stay cheap where template interpolation would allocate an intermediate
-* string per line.
+* The `write*` methods append directly to the output string, and the
+* `render*` methods return fragments for the caller to place. Output
+* accumulates by appending, because engines represent growing strings as
+* ropes. Appends stay cheap where template interpolation would allocate
+* an intermediate string per line.
 */
 var Writer = class {
 	/** The document text accumulated so far. */
 	out = "";
-	/** Current nesting depth; one tab per level. */
+	/** Current nesting depth, one tab per level. */
 	indent = 0;
 	/** Display comment per referenced uuid, derived once from the object graph. */
 	comments;
 	/**
-	* Rendered string values by input string: `id /* comment *​/` for
-	* referenced uuids, quoted text for everything else. Referenced objects
-	* render at least twice (their section entry plus each referencing site)
-	* and build settings repeat across configurations, so most renders are
-	* cache hits. The map lives for one build call only.
+	* Rendered string values keyed by input string. Referenced uuids render
+	* as `id /* comment *​/` and everything else as quoted text. Referenced
+	* objects render at least twice (their section entry plus each
+	* referencing site) and build settings repeat across configurations, so
+	* most renders are cache hits. The map lives for one build call only.
 	*/
 	renderedReferences = /* @__PURE__ */ new Map();
 	/**
@@ -568,7 +568,7 @@ var Writer = class {
 	*/
 	quotedKeys = /* @__PURE__ */ new Map();
 	/**
-	* Serializes the whole document eagerly; read it back with
+	* Serializes the whole document eagerly. Read it back with
 	* {@link toString}.
 	*
 	* @param root The document root dictionary.
@@ -606,7 +606,7 @@ var Writer = class {
 	*
 	* Most calls hit the cache, and the writers call this for every key and
 	* reference, so the method body stays small enough for the engine to
-	* inline; the miss path lives in {@link renderReferenceUncached}.
+	* inline. The miss path lives in {@link renderReferenceUncached}.
 	*/
 	renderReference(id) {
 		const cached = this.renderedReferences.get(id);
@@ -647,8 +647,8 @@ var Writer = class {
 	* Renders a string value in its key's context.
 	*
 	* `remoteGlobalIDString` and `TestTargetID` hold uuids of objects in
-	* another container; annotating them with this container's comments would
-	* be wrong, so they render bare.
+	* another container. Annotating them with this container's comments
+	* would be wrong, so they render bare.
 	*/
 	renderStringValue(key, value) {
 		if (key === "remoteGlobalIDString" || key === "TestTargetID") return ensureQuotes(value);
@@ -658,7 +658,7 @@ var Writer = class {
 	* Appends the entries of a dictionary, one `key = value;` line each.
 	*
 	* Value paths (`$.objects.AA….name`) exist for error messages and are
-	* only constructed in the branches that recurse or throw; the flat string
+	* only constructed in the branches that recurse or throw. The flat string
 	* and number lines that dominate documents skip the concatenation.
 	*
 	* @param object The dictionary whose entries to write.
@@ -797,18 +797,18 @@ var Writer = class {
 /**
 * Serializes a project document to `project.pbxproj` text.
 *
-* The input is the same shape {@link parsePbxproj} produces; see the module
-* documentation of `types.ts` for the value model. Output is stable: two
+* The input is the same shape {@link parsePbxproj} produces. See the module
+* documentation of `types.ts` for the value model. Output is stable, so two
 * calls with semantically equal documents produce identical text, and the
 * layout matches what Xcode itself writes so diffs stay minimal.
 *
 * @param root The document root. Real project documents carry `objects`,
 *   `rootObject`, and the version fields, but any dictionary serializes.
 * @returns The document text, terminated by a newline.
-* @throws PbxprojBuildError when a value has no pbxproj representation:
-*   `null`, `undefined`, booleans, bigints, functions, symbols, class
-*   instances, or non-finite numbers. The error names the path of the
-*   offending value.
+* @throws PbxprojBuildError when a value has no pbxproj representation,
+*   meaning `null`, `undefined`, booleans, bigints, functions, symbols,
+*   class instances, or non-finite numbers. The error names the path of
+*   the offending value.
 */
 function buildPbxproj(root) {
 	if (!isDictionary(root)) throw new PbxprojBuildError("The document root must be a dictionary", "$");
@@ -819,15 +819,15 @@ function buildPbxproj(root) {
 /**
 * Names and well-known values of the pbxproj object vocabulary.
 *
-* Everything here mirrors strings Xcode itself writes; nothing is invented.
-* Centralizing them keeps the object model free of string literals and
-* gives call sites one place to import from.
+* Everything here mirrors strings Xcode itself writes, and nothing is
+* invented. Centralizing them keeps the object model free of string
+* literals and gives call sites one place to import from.
 *
 * @module
 */
 /**
 * The `isa` names the object model works with. The parser and serializer
-* accept any isa; this list only covers the kinds the model creates or
+* accept any isa, and this list only covers the kinds the model creates or
 * gives typed access to.
 */
 const Isa = {
@@ -959,7 +959,7 @@ const CopyFilesDestination = {
 };
 /**
 * Resolves the embed phase destination for an extension-like product type.
-* Watch applications are embedded by product type here; callers that only
+* Watch applications are embedded by product type here. Callers that only
 * know build settings should check the deployment-target key instead.
 */
 function embedDestinationFor(productType) {
@@ -1047,7 +1047,7 @@ function ensureArray(object, key) {
 * Collects the string items of a possibly absent, possibly mixed array.
 *
 * Reference lists in well-formed documents contain only id strings, but a
-* malformed document can mix in anything; non-strings are skipped rather
+* malformed document can mix in anything. Non-strings are skipped rather
 * than thrown on, matching the library's soft-failure stance on reads.
 */
 function stringItems(value) {
@@ -1179,8 +1179,8 @@ var XcodeObject = class {
 	* nested dictionaries keyed by object id (such as the root project's
 	* `TargetAttributes`) drop its entry.
 	*
-	* This is the low-level removal; it does not cascade to objects that only
-	* made sense alongside this one. Higher-level operations like
+	* This is the low-level removal, so it does not cascade to objects that
+	* only made sense alongside this one. Higher-level operations like
 	* {@link XcodeProject.removeTarget} compose it into full teardowns.
 	*/
 	removeFromProject() {
@@ -1193,9 +1193,9 @@ var XcodeObject = class {
 * Typed views over the document object kinds that are not targets, from
 * groups and build phases to version groups and reference proxies.
 *
-* Each class adds the accessors and mutations its kind supports; everything
-* ultimately reads and writes the raw dictionaries through the base class,
-* so mixing model calls with direct property access stays safe.
+* Each class adds the accessors and mutations its kind supports.
+* Everything ultimately reads and writes the raw dictionaries through the
+* base class, so mixing model calls with direct property access stays safe.
 *
 * @module
 */
@@ -1257,7 +1257,7 @@ var Group = class Group extends XcodeObject {
 	* it to the group's children.
 	*
 	* The reference's `lastKnownFileType` derives from the file extension
-	* when it is a known kind; otherwise the reference carries no type and
+	* when it is a known kind. Otherwise the reference carries no type and
 	* Xcode re-derives one on open.
 	*
 	* @param path File path relative to the group, for example
@@ -1293,8 +1293,8 @@ var VariantGroup = class extends Group {
 var BuildPhase = class extends XcodeObject {
 	/**
 	* The phase's display name, when it carries an explicit one. Xcode names
-	* copy-files and shell-script phases; the standard phases derive their
-	* names from their isa.
+	* copy-files and shell-script phases, while the standard phases derive
+	* their names from their isa.
 	*/
 	get name() {
 		return this.getString("name");
@@ -1334,7 +1334,7 @@ var BuildPhase = class extends XcodeObject {
 	* @param reference The file reference or package product the build file
 	*   should point at.
 	* @param options.referenceKey Which build-file field carries the
-	*   reference: `fileRef` for file references (the default) or
+	*   reference, either `fileRef` for file references (the default) or
 	*   `productRef` for Swift package products.
 	* @param options.settings Optional per-file settings, for example
 	*   `{ ATTRIBUTES: ["RemoveHeadersOnCopy"] }`.
@@ -1447,7 +1447,7 @@ var BuildFile = class extends XcodeObject {
 	/**
 	* The view of the file reference the build file points at, when it
 	* points at one. Build files for Swift package products carry a
-	* `productRef` instead; see {@link productDependency}.
+	* `productRef` instead, resolved through {@link productDependency}.
 	*/
 	fileReference() {
 		return this.project.get(this.getString("fileRef"));
@@ -1480,12 +1480,12 @@ var SyncRootGroup = class extends XcodeObject {
 	*
 	* Xcode keeps one exception set per target and folder, so when this
 	* group already carries a set for the target, the file names merge into
-	* it instead of creating a second set; names already excluded are not
-	* duplicated.
+	* it instead of creating a second set, and names already excluded are
+	* not duplicated.
 	*
 	* The standard use is keeping a scaffolded `Info.plist` from being
-	* double-copied: the build already processes it through the target's
-	* `INFOPLIST_FILE` setting.
+	* double-copied, since the build already processes it through the
+	* target's `INFOPLIST_FILE` setting.
 	*
 	* @param target The target whose membership the exceptions restrict.
 	* @param membershipExceptions File names inside the folder to exclude.
@@ -1816,9 +1816,10 @@ var ReferenceProxy = class extends XcodeObject {
 * NeXTSTEP character set for byte values 0x80-0xFF, indexed by `byte - 0x80`.
 *
 * Octal escapes are how pre-Unicode NeXTSTEP text encoded non-ASCII
-* characters; mapping them through this table is what makes `\341` decode to
-* `Æ` instead of the Latin-1 `á`. Values are Unicode code points, per the
-* published NEXTSTEP.TXT vendor mapping in the Unicode Character Database.
+* characters, and mapping them through this table is what makes `\341`
+* decode to `Æ` instead of the Latin-1 `á`. Values are Unicode code
+* points, per the published NEXTSTEP.TXT vendor mapping in the Unicode
+* Character Database.
 */
 const NEXT_STEP_MAPPINGS = [
 	160,
@@ -1953,8 +1954,8 @@ const NEXT_STEP_MAPPINGS = [
 /**
 * Maps an octal escape value to its Unicode code point.
 *
-* Values below 0x80 are ASCII and pass through; values in 0x80-0xFF select
-* from the NeXTSTEP character set.
+* Values below 0x80 are ASCII and pass through, while values in 0x80-0xFF
+* select from the NeXTSTEP character set.
 */
 function nextStepToUnicode(code) {
 	if (code < 128 || code > 255) return code;
@@ -2063,7 +2064,8 @@ function unescapeString(input) {
 * @module
 */
 /**
-* Characters allowed in unquoted string literals: `[A-Za-z0-9_$/:.-]`.
+* The characters allowed in unquoted string literals are
+* `[A-Za-z0-9_$/:.-]`.
 *
 * A 256-entry lookup table keyed by code unit keeps classification to a
 * single array read in the hot loop. Non-ASCII units index past the table
@@ -2124,7 +2126,7 @@ function isDigit(code) {
 * Scanner state and grammar productions for one parse call.
 *
 * The parser holds a single cursor into the source string and advances it
-* through the `read*` and `parse*` methods; there is no separate tokenizer
+* through the `read*` and `parse*` methods. There is no separate tokenizer
 * stage and no token objects.
 */
 var Parser$1 = class {
@@ -2135,7 +2137,7 @@ var Parser$1 = class {
 	/**
 	* Offset of an unterminated block comment the trivia scanner consumed, or
 	* -1. Recording it instead of throwing keeps the trivia scanner free of
-	* failure branches; see {@link fail}.
+	* failure branches, and {@link fail} reports it.
 	*/
 	unterminatedCommentAt = -1;
 	/**
@@ -2149,13 +2151,13 @@ var Parser$1 = class {
 	* failure.
 	*
 	* An unterminated block comment swallows the rest of the input, so any
-	* failure raised after one (always some end-of-input error) is a symptom;
-	* the comment itself is reported instead. Content after the root value is
-	* never scanned, so a trailing unterminated comment still parses, as
-	* Apple's parser accepts it too.
+	* failure raised after one (always some end-of-input error) is a symptom
+	* and the comment itself is reported instead. Content after the root
+	* value is never scanned, so a trailing unterminated comment still
+	* parses, as Apple's parser accepts it too.
 	*
 	* @param message Failure description without location.
-	* @param offset Offset of the failure; defaults to the current cursor.
+	* @param offset Offset of the failure, defaulting to the current cursor.
 	*/
 	fail(message, offset = this.pos) {
 		if (this.unterminatedCommentAt !== -1) throw new PbxprojParseError("Unterminated block comment", this.input, this.unterminatedCommentAt);
@@ -2251,11 +2253,11 @@ var Parser$1 = class {
 		return input.slice(start, pos);
 	}
 	/**
-	* Reads a quoted string; the opening quote is at the current position.
+	* Reads a quoted string whose opening quote is at the current position.
 	*
-	* The scan tracks whether any escape sequence occurred: unescaped strings
-	* (the overwhelming majority) return as a direct slice, and only escaped
-	* ones pay for {@link unescapeString}.
+	* The scan tracks whether any escape sequence occurred, so unescaped
+	* strings (the overwhelming majority) return as a direct slice, and only
+	* escaped ones pay for {@link unescapeString}.
 	*/
 	readQuotedString() {
 		const input = this.input;
@@ -2304,7 +2306,7 @@ var Parser$1 = class {
 		return bytes;
 	}
 	/**
-	* Parses the document root: a dictionary or an array.
+	* Parses the document root, which is a dictionary or an array.
 	*/
 	parseDocument() {
 		const code = this.peek();
@@ -2314,7 +2316,7 @@ var Parser$1 = class {
 		this.fail(`Expected '{' or '(' at the start of the document but found '${this.input[this.pos]}'`);
 	}
 	/**
-	* Parses a `{ key = value; ... }` dictionary; the `{` is at the current
+	* Parses a `{ key = value; ... }` dictionary whose `{` is at the current
 	* position. Keys may be quoted or unquoted, and every entry requires the
 	* `=` and terminating `;`.
 	*/
@@ -2348,9 +2350,9 @@ var Parser$1 = class {
 		}
 	}
 	/**
-	* Parses a `( item, item, ... )` array; the `(` is at the current
-	* position. A trailing comma before `)` is allowed; Xcode writes one
-	* after every item.
+	* Parses a `( item, item, ... )` array whose `(` is at the current
+	* position. A trailing comma before `)` is allowed, because Xcode writes
+	* one after every item.
 	*/
 	parseArray() {
 		const input = this.input;
@@ -2397,12 +2399,12 @@ var Parser$1 = class {
 /**
 * Decides whether an unquoted literal is a number or a string.
 *
-* One loop with an early exit: the first character outside `[0-9.]` (after
-* an optional leading `-`) settles the token as a string, so the
-* 24-character identifiers that dominate project documents are classified
-* within their first few characters.
+* The decision is one loop with an early exit. The first character outside
+* `[0-9.]` (after an optional leading `-`) settles the token as a string,
+* so the 24-character identifiers that dominate project documents are
+* classified within their first few characters.
 *
-* Numeric-looking candidates convert under a single print-back rule: the
+* Numeric-looking candidates convert under a single print-back rule. The
 * literal becomes a number exactly when the number formats back to the
 * identical text. Any literal the conversion would reshape stays a string,
 * so a parse and build cycle cannot change a single byte of any scalar.
@@ -2440,13 +2442,34 @@ function interpretLiteral(literal) {
 * @param text Source text of the document.
 * @returns The document's root value. For real project files this is the
 *   root dictionary with `objects`, `rootObject`, and version fields.
-* @throws PbxprojParseError when the document is malformed; the error
+* @throws PbxprojParseError when the document is malformed. The error
 *   carries the line and column of the failure.
 */
 function parsePbxproj(text) {
 	return new Parser$1(text).parseDocument();
 }
 //#endregion
+//#region src/rename.ts
+/**
+* The stem-matching rule shared by the rename flows. The project model
+* renames product file references and host paths with it, and the scheme
+* model renames buildable names with it, so both sides agree on what
+* counts as the renamed target's file.
+*
+* @module
+*/
+/**
+* Renames a file name whose stem is the target name, keeping the
+* extension. `SampleApp` and `SampleApp.app` rename, and so does a
+* multi-part extension like `SampleApp.app.dSYM`. A name whose stem
+* merely starts with the old name, like `SampleAppTests.xctest`, is a
+* different target's product and returns `undefined`.
+*/
+function renameFileNameStem(fileName, oldName, newName) {
+	if (fileName === oldName) return newName;
+	if (fileName.startsWith(`${oldName}.`)) return newName + fileName.slice(oldName.length);
+}
+//#endregion
 //#region src/md5.ts
 /**
 * Embedded MD5, implemented from RFC 1321.
@@ -2454,8 +2477,8 @@ function parsePbxproj(text) {
 * Deterministic object ids hash their seed text (see `uuid.ts`), and the
 * library runs in every JavaScript runtime without depending on a crypto
 * module, so the digest is implemented here. MD5 is used strictly as a
-* stable text-to-bits mapping for identifier generation; nothing security
-* relevant derives from it.
+* stable text-to-bits mapping for identifier generation, and nothing
+* security relevant derives from it.
 *
 * @module
 */
@@ -2530,7 +2553,7 @@ const SHIFTS = [
 	21
 ];
 /**
-* Step constants for the 64 steps: the integer parts of
+* Step constants for the 64 steps, which are the integer parts of
 * `abs(sin(i + 1)) * 2^32`, as RFC 1321 section 3.4 tabulates them. The
 * values are fixed by the specification rather than derived through
 * `Math.sin` at load, because the digest feeds deterministic identifiers
@@ -2604,9 +2627,9 @@ const SINES = new Uint32Array([
 	3951481745
 ]);
 /**
-* Encodes text as UTF-8 bytes with RFC 1321 padding applied: a `0x80`
-* terminator, zero fill to 56 bytes mod 64, then the bit length as a
-* little-endian 64-bit integer.
+* Encodes text as UTF-8 bytes with RFC 1321 padding applied, meaning a
+* `0x80` terminator, zero fill to 56 bytes mod 64, then the bit length as
+* a little-endian 64-bit integer.
 */
 function paddedUtf8(text) {
 	const bytes = new TextEncoder().encode(text);
@@ -2624,8 +2647,8 @@ function paddedUtf8(text) {
 /**
 * Adds two 32-bit values with wraparound, keeping intermediates inside the
 * 32-bit range JavaScript bitwise operators preserve. `Math.trunc` is not
-* a substitute here: the bitwise coercion is what performs the modular
-* wrap the algorithm requires.
+* a substitute here, because the bitwise coercion is what performs the
+* modular wrap the algorithm requires.
 */
 function add32(a, b) {
 	return a + b | 0;
@@ -2697,7 +2720,7 @@ function md5Hex(text) {
 * Deterministic object identifiers for generated pbxproj objects.
 *
 * Xcode identifies every object with 24 hexadecimal characters. Generated
-* ids here are deterministic: the same seed always produces the same id, so
+* ids here are deterministic. The same seed always produces the same id, so
 * programmatic edits are reproducible and diffs stay minimal across runs.
 * The format is `XX` + the first 20 characters of `md5(seed)` + `XX`, which
 * is a valid identifier that remains recognizable as generated.
@@ -2940,7 +2963,7 @@ function defaultConfigurationSettingsOf(project, configurationListId) {
 * extends it with products, embedding, synchronized folders, Swift
 * packages, and system frameworks.
 *
-* Reads are deliberately soft: user-generated projects can be malformed,
+* Reads are deliberately soft. User-generated projects can be malformed,
 * so lookups return `undefined` instead of throwing wherever a document
 * could legally or illegally omit something. Mutations create any missing
 * structure they need.
@@ -2993,11 +3016,11 @@ var Target = class extends XcodeObject {
 	*
 	* Configurations based on `.xcconfig` files take part once the files
 	* are registered through {@link XcodeProject.registerXcconfig}, in
-	* Xcode's order: target settings, the target's xcconfig, project
-	* settings, the project's xcconfig.
+	* Xcode's order of target settings, then the target's xcconfig, then
+	* project settings, then the project's xcconfig.
 	*
-	* Only string values are returned; a list- or number-valued setting reads
-	* as `undefined`.
+	* Only string values are returned, so a list- or number-valued setting
+	* reads as `undefined`.
 	*/
 	getBuildSetting(key) {
 		const targetConfiguration = defaultConfigurationOf(this.project, this.getString("buildConfigurationList"));
@@ -3372,7 +3395,7 @@ var LegacyTarget = class extends Target {
 * `project.pbxproj`.
 *
 * The model is a set of lightweight views over the plain parsed document.
-* All state lives in the document itself; views hold only an id and a
+* All state lives in the document itself. Views hold only an id and a
 * project reference, so model mutations and direct dictionary writes
 * compose freely and {@link XcodeProject.build} always serializes the
 * current state. New objects receive deterministic identifiers (see
@@ -3402,7 +3425,7 @@ var RootProject = class extends XcodeObject {
 	}
 	/**
 	* The settings dictionary of the project-level default configuration.
-	* Targets inherit from these settings; see
+	* Targets inherit from these settings, as described on
 	* {@link NativeTarget.getBuildSetting}.
 	*/
 	defaultConfigurationSettings() {
@@ -3477,7 +3500,7 @@ var XcodeProject = class XcodeProject {
 	}
 	/**
 	* Wraps an already parsed document in a model. The document is used in
-	* place, not copied; model mutations write into it.
+	* place rather than copied, so model mutations write into it.
 	*/
 	static fromDocument(document) {
 		return new XcodeProject(document);
@@ -3492,7 +3515,7 @@ var XcodeProject = class XcodeProject {
 	/**
 	* The raw properties dictionary of an object.
 	*
-	* @throws XcodeModelError when no object with the id exists; views use
+	* @throws XcodeModelError when no object with the id exists. Views use
 	*   this accessor, so a view of a deleted object fails loudly instead of
 	*   resurrecting the entry.
 	*/
@@ -3535,8 +3558,8 @@ var XcodeProject = class XcodeProject {
 	}
 	/**
 	* Generates a deterministic 24-character id from a seed, avoiding every
-	* id the document currently contains. The id is not reserved; adding an
-	* object with it (see {@link add}) is what claims it.
+	* id the document currently contains. The id is not reserved, and only
+	* adding an object with it (see {@link add}) claims it.
 	*/
 	generateId(seed) {
 		return generateObjectId(seed, new Set(Object.keys(this.objectsDictionary)));
@@ -3643,7 +3666,8 @@ var XcodeProject = class XcodeProject {
 	* and Resources build phases, and registers it on the project.
 	*
 	* @throws XcodeModelError for product types the model cannot create a
-	*   product reference for; see {@link AddNativeTargetOptions.productType}.
+	*   product reference for, listed on
+	*   {@link AddNativeTargetOptions.productType}.
 	*/
 	addNativeTarget(options) {
 		const productInfo = PRODUCT_FILE_INFO[options.productType];
@@ -3689,7 +3713,7 @@ var XcodeProject = class XcodeProject {
 	/**
 	* Adds a remote Swift package reference and registers it on the project.
 	* When the project already references the repository, the existing
-	* reference is returned unchanged, requirement included; adjust an
+	* reference is returned unchanged, requirement included. Adjust an
 	* existing requirement through the reference's properties. Link products
 	* to targets with {@link NativeTarget.addSwiftPackageProduct}.
 	*
@@ -3764,7 +3788,7 @@ var XcodeProject = class XcodeProject {
 	* list containing it, or a nested dictionary carrying it as a key or
 	* string value.
 	*
-	* The scan is linear over the document; removal flows call it once per
+	* The scan is linear over the document. Removal flows call it once per
 	* removed object, which keeps teardown proportional to what is actually
 	* removed.
 	*/
@@ -3780,7 +3804,7 @@ var XcodeProject = class XcodeProject {
 	* (such as `TargetAttributes`) drop its entry.
 	*
 	* Removing an id the document does not contain is a no-op. This is the
-	* low-level removal; {@link removeTarget} composes it into a full
+	* low-level removal, and {@link removeTarget} composes it into a full
 	* teardown.
 	*/
 	removeObject(id) {
@@ -3798,7 +3822,7 @@ var XcodeProject = class XcodeProject {
 	* dependencies on others), its membership exception sets, and
 	* synchronized folders no remaining target links.
 	*
-	* On-disk sources are untouched; the removal is document-only, like
+	* On-disk sources are untouched. The removal is document-only, like
 	* deleting a target in Xcode and keeping its folder.
 	*
 	* @throws XcodeModelError when the target belongs to another project,
@@ -3841,12 +3865,58 @@ var XcodeProject = class XcodeProject {
 		for (const groupId of syncGroupIds) if (!this.nativeTargets().some((remaining) => stringItems(remaining.properties["fileSystemSynchronizedGroups"]).includes(groupId))) this.removeObject(groupId);
 	}
 	/**
+	* Renames a target and every place the document knows it by name. That
+	* covers the target's `name` and `productName`, its product file
+	* reference (`OldName.app` becomes `NewName.app`, whatever the
+	* extension), the `remoteInfo` of container item proxies pointing at
+	* the target, `TEST_TARGET_NAME` settings naming it, and the path
+	* segments of `TEST_HOST` and `BUNDLE_LOADER` settings that name the
+	* target or its product. A `PRODUCT_NAME` of the target's own
+	* configurations is rewritten only when it spells the old name
+	* literally. The usual `$(TARGET_NAME)` follows by itself.
+	*
+	* Scheme files live outside the pbxproj, so buildable references are
+	* renamed separately through `Xcscheme.renameTarget`. On-disk renames
+	* (source folders, entitlements files) and the group paths pointing at
+	* those folders stay with the caller. Sibling targets such as
+	* `OldNameTests` are renamed with their own calls.
+	*
+	* @throws XcodeModelError when the target belongs to another project.
+	*/
+	renameTarget(target, newName) {
+		if (target.project !== this) throw new XcodeModelError("Cannot rename a target that belongs to another project");
+		const oldName = target.name;
+		if (oldName === newName) return;
+		target.set("name", newName);
+		if (oldName == null) return;
+		if (target.getString("productName") === oldName) target.set("productName", newName);
+		const product = this.get(target.getString("productReference"));
+		if (product != null) for (const key of ["path", "name"]) {
+			const fileName = product.getString(key);
+			const renamed = fileName == null ? void 0 : renameFileNameStem(fileName, oldName, newName);
+			if (renamed != null) product.set(key, renamed);
+		}
+		for (const configuration of target.buildConfigurations()) {
+			const settings = configuration.buildSettings;
+			if (settings?.PRODUCT_NAME === oldName) settings.PRODUCT_NAME = newName;
+		}
+		for (const [, view] of this.objects()) {
+			if (ContainerItemProxy.is(view) && view.getString("remoteGlobalIDString") === target.id && view.remoteInfo === oldName) view.set("remoteInfo", newName);
+			if (BuildConfiguration.is(view)) {
+				const settings = view.buildSettings;
+				if (settings == null) continue;
+				if (settings.TEST_TARGET_NAME === oldName) settings.TEST_TARGET_NAME = newName;
+				renameHostPathSettings(settings, oldName, newName);
+			}
+		}
+	}
+	/**
 	* Finds a file reference by its project-relative path, resolving each
 	* reference's location through the group tree from the main group
 	* (nested group `path` components join with `/`).
 	*
 	* Members of file-system-synchronized folders are not listed in the
-	* document and therefore cannot be found; check
+	* document and therefore cannot be found. Check
 	* {@link NativeTarget.syncGroupPaths} for folder-level containment
 	* instead.
 	*/
@@ -3933,6 +4003,31 @@ function joinPath(prefix, segment) {
 	return prefix === "" ? segment : `${prefix}/${segment}`;
 }
 /**
+* Renames the segments of a path-valued build setting that name the
+* target or one of its products. Settings like `TEST_HOST` embed the
+* product path as
+* `$(BUILT_PRODUCTS_DIR)/SampleApp.app/.../SampleApp`, so each segment
+* is matched whole against the target name. Substring occurrences inside
+* unrelated segments stay untouched.
+*/
+function renamePathSegments(value, oldName, newName) {
+	return value.split("/").map((segment) => renameFileNameStem(segment, oldName, newName) ?? segment).join("/");
+}
+/**
+* Renames the target name inside the host-path settings of one
+* configuration. `TEST_HOST` and `BUNDLE_LOADER` carry the hosting
+* product's path, so their segments rename the way the product file
+* reference does.
+*/
+function renameHostPathSettings(settings, oldName, newName) {
+	for (const key of ["TEST_HOST", "BUNDLE_LOADER"]) {
+		const value = asString(settings[key]);
+		if (value == null) continue;
+		const rewritten = renamePathSegments(value, oldName, newName);
+		if (rewritten !== value) settings[key] = rewritten;
+	}
+}
+/**
 * Whether a value references the id anywhere in its structure. A
 * reference is a string equal to it, an array containing it at any depth,
 * or a dictionary carrying it as a key or somewhere in its values.
@@ -3978,7 +4073,7 @@ function stripValue(value, id) {
 	return value;
 }
 /**
-* Strips every reference to the id from an object's properties; see
+* Strips every reference to the id from an object's properties. See
 * {@link stripValue} for the shapes handled. String properties naming the
 * id are deleted rather than left empty.
 */
@@ -4530,6 +4625,46 @@ var Xcscheme = class Xcscheme {
 	buildableReferences() {
 		return this.elements("BuildableReference").map((element) => new BuildableReference(element));
 	}
+	/**
+	* Renames every buildable reference pointing at a target. The blueprint
+	* name is matched whole, and the buildable name is matched by its stem,
+	* so `OldApp.app` becomes `NewApp.app` while `OldAppTests.xctest`, a
+	* different target's product, stays untouched. This is the scheme-file
+	* side of `XcodeProject.renameTarget`. Returns whether anything
+	* changed, so callers can skip rewriting untouched files.
+	*/
+	renameTarget(oldName, newName) {
+		if (oldName === newName) return false;
+		let changed = false;
+		for (const reference of this.buildableReferences()) {
+			if (reference.blueprintName === oldName) {
+				reference.blueprintName = newName;
+				changed = true;
+			}
+			const buildableName = reference.buildableName;
+			const renamed = buildableName == null ? void 0 : renameFileNameStem(buildableName, oldName, newName);
+			if (renamed != null) {
+				reference.buildableName = renamed;
+				changed = true;
+			}
+		}
+		return changed;
+	}
+	/**
+	* Rewrites every buildable reference's container after the
+	* `.xcodeproj` directory itself is renamed, so `container:Old.xcodeproj`
+	* becomes `container:New.xcodeproj`. The project names are matched
+	* exactly. Returns whether anything changed.
+	*/
+	renameContainer(oldProjectName, newProjectName) {
+		if (oldProjectName === newProjectName) return false;
+		let changed = false;
+		for (const reference of this.buildableReferences()) if (reference.referencedContainer === `container:${oldProjectName}.xcodeproj`) {
+			reference.referencedContainer = `container:${newProjectName}.xcodeproj`;
+			changed = true;
+		}
+		return changed;
+	}
 };
 /**
 * Creates the scheme Xcode writes for an application target. The
@@ -4664,8 +4799,8 @@ function buildXcconfig(document) {
 */
 const INCLUDE_PATTERN = /^#include(\?)?\s*"([^"]*)"\s*(?:\/\/.*)?$/u;
 /**
-* Matches the head of an assignment: leading whitespace, the setting
-* name, and the raw conditions block up to the equals sign.
+* Matches the head of an assignment, which is the leading whitespace, the
+* setting name, and the raw conditions block up to the equals sign.
 */
 const ASSIGNMENT_HEAD_PATTERN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*((?:\[[^\]]*\])*)\s*=/u;
 /**
@@ -4777,7 +4912,7 @@ function parseXcconfig(source) {
 * Object model for Xcode build configuration files (`.xcconfig`).
 *
 * {@link Xcconfig} wraps a parsed document the way `XcodeProject` wraps a
-* pbxproj: the document stays the single source of truth, reads and
+* pbxproj. The document stays the single source of truth, reads and
 * writes go through it, and {@link Xcconfig.build} emits it back with
 * untouched lines preserved byte for byte.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rork-xcode",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Zero-dependency Xcode project (pbxproj) and scheme (xcscheme) parser, builder, and object model that runs identically in every JavaScript runtime",
   "keywords": [
     "apple",